Integrationsanleitung Magento 2

Einleitung

Unser Magento2-Plugin wird regelmäßig aktualisiert und bietet eine vielseitige, sofort einsatzbereite Lösung zur einfachen Annahme von Online-Zahlungen:

Derzeit unterstützte Zahlungsarten:

  • Kreditkarten (Visa, Mastercard, American Express, JCB, Diners Club, Maestro International, Carde Bleue)
  • Amazon Pay (V1)
  • Alipay
  • Apple Pay
  • Bancontact
  • Barzahlen
  • EPS
  • iDEAL
  • Klarna Payments
  • Giropay
  • PAYONE gesicherte Rechnung
  • PAYONE gesicherter Rechnungskauf, gesicherte Lastschrift und gesicherter Ratenkauf
  • PAYONE Lastschrift
  • PAYONE offene Rechnung
  • PAYONE Vorkasse
  • PayPal und PayPal Express
  • PostFinance Card und E-Finance
  • Przelewy24
  • Sofort
  • Ratepay Rechnungskauf, Lastschrift und Ratenkauf
  • Trustly
  • Unzer Rechnungskauf, Lastschrift und Ratenkauf
  • WeChat Pay

Behalten Sie unsere Release Notes im Auge, um über Updates und neue Funktionen (z.B. Zahlungsmethoden, Funktionen, Integrationsmodi) informiert zu bleiben, die wir diesem Plugin hinzugefügt haben!

Schauen Sie sich unsere Dokumentation an, um zu erfahren, wie Sie Ihren Shop mit unserer Plattform verbinden können, um von allen Funktionen zu profitieren!

Aktuelles Release: v3.9

Voraussetzungen

Sie brauchen unbedingt einen aktiven PAYONE – Account. Wenn Sie noch keinen Account haben, kontaktieren Sie uns bitte.

Installation des Plugins

Sie haben 2 Möglichkeiten unser Plugin zu installieren:

Installation via Composer

composer require payone-gmbh/magento-2
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean

Installation via Github

Konfiguration im PAYONE - Portal

Um den Transaktionsstatus an die richtige Adresse zu senden, melden Sie sich bitte im PAYONE Merchant Interface (PMI) an.

<SHOPURL>/index.php/payone/transactionstatus

Bitte belassen Sie die Hash-Prüfung auf "md5 oder sha2-384 (für Migration)", um eine korrekte Kommunikation zwischen PAYONE und dem Shop zu gewährleisten.
Additional Response-data

Setzen Sie unter General, die Additional Response-data sowohl für Live als auch für Test auf "on".

Konfiguration im Magento2 - Admin

  • Klicken Sie unter PAYONE → Allgemein

  • Tragen Sie hier bitte Ihre Zugangsdaten, aus dem PMI, ein:

Wir empfehlen dringend, maximal 5 Zeichen als Präfix zu verwenden. Ist kein Refentenznummernpräfix gesetzt, wird nur die Magento-Bestellnummer übermittelt.
  • Legen Sie fest ob nach einer erfolgreichen Zahlung per "Autorisierung" automatisch eine E-Mail mit der Rechnung an den Kunden senden soll:

  • Jede Zahlungsart kann mit separaten Zugangsdaten genutzt werden. Diese können direkt in der Zahlungsart eingetragen werden.
Konfiguration der Zahlungsarten
  • Klicken Sie unter PAYONE → Zahlarten

  • Aktivieren/ Deaktivieren Sie die gewünschten Zahlungsarten im Feld "Aktiviert".

Aufgrund von Einschränkungen, die in Magento 2.3.1 eingeführt wurden, sind alle Zahlungsmethoden nach der Erstinstallation standardmäßig aktiv. Bitte stellen Sie sicher, dass Sie alle Zahlungsmethoden, die Sie nicht benötigen, vor dem Start deaktivieren!
Spezielle Anpassungen
Gesicherter Rechnungskauf (neu) + Gesicherter Ratenkauf

Diese beiden Zahlungsarten benötigen ein eigenes Zahlungsportal. Bitte gehen Sie unter PAYONE → Zahlarten → Gesicherter Rechnungskauf (neu) bzw. Gesicherter Ratenkauf → Nutze Globale Einstellungen auf "Nein" und eine separate Portal ID eintragen.

Wenn die Bestellungen teilgecaptured werden, müssen die Refunds in der gleichen Höhe erstellt werden. Hintergrund ist, dass bei jedem Capture eine neue Forderung entsteht.

Klarna
Die Klarna-Zahlungsmethoden:
 - Klarna Rechung
 - Klarna Lastschrift
 - Klarna Ratenkauf
sind in einer Klarna Basiszahlungsmethode zusammengefasst.

Ratepay
Ratepay erfordert die Einstellung einer oder mehrerer Shop-IDs. Diese erhalten Sie von Ratepay. Klicken Sie nach dem Hinzufügen auf "Ratepay Shop-IDs aktualisieren". Gültige Shop-IDs werden mit ihrer von Ratepay festgelegten Konfiguration angezeigt.

Amazon Pay
Integrationseinstellungen in Seller Central
Bitte tragen Sie im Punkt "Integrationseinstellungen" in Seller Central unter Integrator-URL folgende URL ein: https://gpc-sys.pay1.de/gpc/amazon/1.0/notify - die "Seller URL" kann leer bleiben. Diese URL stellt sicher, dass der Shop alle Benachrichtigungen von Amazon erhält.
Bitte stellen Sie auch sicher, dass Sie alle URLs Ihres Shops als erlaubte Javascript Origin in Seller Central speichern.
  1. Wählen Sie auf der Seller Central-Startseite in der Navigationsleiste oben links "Integration - Integration Central".
  2. Scrollen Sie auf der Seite "Integration Central" nach unten zum Abschnitt "Kunden-ID/Shop-ID(s) verwalten" und klicken Sie auf "Kunden-ID/Shop-ID(s) anzeigen".
  3. Wenn Sie eine bestehende Kunden- oder Shop-ID registriert haben, überprüfen Sie die Konfiguration des ausgewählten Shops. Sie können auf den Link "Bearbeiten" auf der rechten Seite klicken, um die Informationen zu bearbeiten.
  4. Wenn Sie auf die Schaltfläche "Bearbeiten" klicken, können Sie alle Details der Kundenkonfiguration bearbeiten.
  5. Wenn Sie ab Schritt 3 auf den Link "Neue Konfiguration erstellen" oben klicken, können Sie eine neue Kundenkonfiguration erstellen und alle relevanten Informationen angeben.

Abrufen der Konfiguration im Magento-Backend

Um die Zahlungsmethode zu aktivieren, verwenden Sie bitte den Button "get configuration". Dies ruft Ihre Kunden-ID und Verkäufer-ID von unserer Plattform ab. Sie sollten dann die Werte in den entsprechenden Feldern sehen.

Aktivieren Sie die Zahlungsmethode

Bitte beachten Sie, dass Sie nur dann Live-Zahlungen vornehmen können, wenn die Zahlungsmethode für Live-Zahlungen in Seller Central zugelassen ist.

 

Feld Beschreibung

Amazon Client ID

Zeigt die derzeitige Client ID

Amazon Seller ID

Zeigt die derzeitige Seller ID

Get configuration

Mit diesem Button erhalten Sie die Konfiguration von PAYONE

Diese Zahlungsart funktioniert nicht, bevor die Konfiguration gespeichert wurde!

Amazon Button Type

  • Amazon Pay (normal) 
  • Pay (smaller)
  • Amazon Pay (smallest)

Amazon Button Type

  • Gold
  • Light grey
  • Dark grey

Amazon Mode

  • Automatic (verwendet die Standardsprache)
  • Englisch
  • Deutsch
  • French
  • Italian
  • Spanish

Amazon Mode
 

  • Always Synchronous
  • Asynchronous on failure
In manchen Fällen kann es zu einer Interferenz zwischen unserem Plugin und dem Amazon-Plugin im Magento Core kommen. Wenn Sie also ein "seltsames Verhalten" feststellen, wie z.B. das Verschwinden von Amazon-Buttons, können Sie den folgenden Befehl im Magento-Root auszuführen:
php bin/magento module:disable Amazon_Payment

Kreditkarte

Wählen Sie unter Kartentyp aus, welche Kreditkarten Sie anbieten wollen.

Das Feld Prüfe Kartenprüfziffer bestimmt, ob die Kreditkartenprüfnummer abgefragt wird.

Aus rein technischer Sicht ist die Abfrage der CVC optional. Die meisten Endkunden sind jedoch an die Abfrage gewöhnt.

PAYONE Lastschrift

Feld Beschreibung

BIC abfrage

Bestimmt, ob die BIC im Checkout abgefragt wird. Verwenden Sie diese Konfiguration für eine bessere Kompatibilität mit Bankkonten von außerhalb der DACH-Region.
 

Download Mandat als PDF

Bei der Auswahl Ja wird nach der Bestellung ein Link angeboten, über den der Endkunde das SEPA-Mandat als PDF-Datei herunterladen kann.

Liste der unterstützten Kontoländer

Mehrfachauswahl der Länder, aus denen die Zahlungsart Lastschrift unterstützt wird. Die PAYONE Plattform unterstützt derzeit nur Lastschriften für deutsche Bankkonten.

Mandatserteilung aktivieren

Soll der SEPA-Mandatsmanager verwendet werden? Eine Prüfung der Bankverbindung ist obligatorisch. Eine Prüfung gegen die POS-Sperrliste ist nicht möglich.

Prüfe Bankverbindung

Schaltet eine Überprüfung der Bankverbindung mittels "bankaccountcheck"-Aufforderung ein.

Diese Einstellung ist Teil unseres optionalen Risk Management Modul

Apple Pay

Feld Beschreibung

Aktiviert

Ja/ Nein

Titel

Name der Zahlart, welcher im Checkout erscheint

Apple Pay Merchant Id

Diesen Wert können Sie dem Apple Developer Portal als "Identifier" Ihrer Merchant ID entnehmen:

Certificate file

Bitte laden Sie Ihr Händleridentifikationszertifikat aus dem Apple Developer Portal im .pem Format hoch. Sie können die Datei merchant_id.cer mit diesem Konsolenbefehl in .pem konvertieren:

Certificate file
openssl x509 -inform der -in merchant_id.cer -outform pem -out merchant_id.pem

Private key file

Bitte laden Sie hier die private Schlüsseldatei hoch, mit der Sie die Apple Pay CSR erstellt haben.

Private key password

Hier können Sie das Passwort zur Verwendung des Private Keys festlegen

Allowed card types

Wählen Sie hier die Kartentypen, die für Apple Pay erlaubt sind. Bitte wählen Sie hier nur die Kartentypen aus, die auch Bestandteil Ihres PAYONE-Vertrags sind.
 

Neben der Konfiguration in Magento ist für den Betrieb von Apple Pay als Zahlart auch das Einrichten der entsprechenden Zertifikate nötig. Hinweise dazu finden Sie hier: Special Remarks - Apple Pay

Zusätzlich verlangt Apple die Validierung der Shop-Domain für Apple Pay. Folgen Sie dafür den Anweisungen im Apple Developer Portal:

Bearbeiten der Bestellungen

Klicken Sie unter PAYONE → Bestellungen

Überblick

Hier finden Sie eine PAYONE-spezifische Bestellübersicht ähnlich der Magento-Bestellübersicht. Neben den Standardinformationen können Sie hier den Zahlungsstatus auf der PAYONE Plattform, die genaue Art der Zahlung (z.B. Kreditkartenmarken) und ggf. den Mahnstatus einsehen. Ein Klick auf Ansicht öffnet die Detailansicht der entsprechenden Bestellung.

Erfassung/ Capture

Vorautorisierte Transaktionen müssen erfasst werden, um den eigentlichen Geldfluss auszulösen. Unter PAYONE → Bestellungen → Bestelldetails → Rechnungsbeleg können Sie mit der Rechnungserstellung den Capture auslösen.

Durch die Auswahl von "Online erfassen" in der oben gezeigten Dropdown-Liste wird die Forderung auf der PAYONE Plattform eingezogen. Wenn Sie das Geld nicht erfassen, aber dennoch eine Rechnung und Forderung erstellen möchten, wählen Sie bitte stattdessen "Offline erfassen".

Teilerfassungen sind ebenfalls möglich, indem Sie einfach die fakturierbare Menge der Artikel anpassen.

Rückerstattung/ Refund

Bereits erfasste Gelder können durch Erstellen einer Gutschrift für eine bestehende Rechnung zurückerstattet werden.

Rufen Sie sich die Rechnungsdetails der Rechnung auf, die gutgeschrieben werden soll. Klicken Sie oben rechts auf Credit Memo.

 

Geben Sie hier ein, welche Summe erstattet werden soll:

 

Mit Klick auf die Schaltfläche "Refund", wird das Geld an die Zahlungsmethode des Kunden zurückgeschickt. "Refund Offline" erstellt die Gutschrift, löst aber keinen Geldfluss aus.

Teilerstattungen sind nach der gleichen Methode wie bei Teilerfassungen möglich. Sie können auch die Summe der Rückerstattung anpassen, um die Gebühren während der Rückerstattung zu berücksichtigen. Bedenken Sie, dass einige Zahlungsarten darauf angewiesen sind, dass die Artikel im Warenkorb mit der ursprünglichen Bestellung übereinstimmen.

Erweiterte Konfigurationen

Hier finden Sie separate Einstellungsmöglichkeiten, mit den Sie unser Plugin genauer an Ihre Bedürfnisse anpassen können:

Rechnungsinformationen senden

Unter PAYONE → Allgemein → Send invoicing information aktivieren Sie die Übermittlung von Artikeldaten, um eine Rechnung auf der PAYONE Plattform zu erstellen.

Der Text kann frei gewählt werden und erscheint als dynamischer Text auf der Rechnung bzw. Gutschrift. Es können verschiedene Magento-Variablen als Platzhalter verwendet werden.

Status Mapping

Unter PAYONE → Allgemein → Status Mapping können die verschiedenen Transaktionsstatus der PAYONE Plattform auf Magento-Bestellstatus abgebildet werden. Wird ein neuer Transaktionsstatus empfangen, wird der entsprechende "Magento-Status" in der Bestellübersicht im Magento-Backend gesetzt. Dies kann für jede Zahlart separat eingetragen werden.

Kreditkarte - CSS Anpassungen

Klicken Sie unter PAYONE → Allgemein → Kreditkartenzahlung → Feldkonfiguration → Benutzerdefinierte Anpassung hosted-Iframe

Feld Beschreibung

Aktiv

Ja/Nein

Anzahl Zeichen

Länge des Feldes in Zeichen (HTML attribute size)

Breite

CSS - Spezifiziert width

CSS

Spezifikation von CSS properties für das Feld

Deaktiviert mit der Vorauswahl des Standard

Fehlerausgabe

Höhe

CSS - Indikator height

iFrame

  • Standard - Verwendet Breite und Höhe vom Standardstils
  • Benutzerdefiniert - Verwendet Breite und Höhe aus den folgenden Feldern
     

iFrame

  • Width - CSS Spezifikation
  • Height - CSS Spezifikation

Language

Wählen Sie die Sprache, in der die Fehlermeldung ausgegeben werden soll.

Standardstil

  • Eingabe - CSS Spezifikation für alle Eingabefelder (HTML input)
  • Auswahl - CSS Spezifikation für alle Auswahlfelder (HTML select )

Stil

  • Standard - Nutzt CSS Spezifikation vom Standard
  • Benutzerdefiniert - Nutzt CSS Spezifikation von den folgenden Feldern

Typ

  • Numerisch - Es sind nur Zahlen erlaubt und für mobile Geräte wird die numerische Tastatur verwendet input type="tel".
  • Passwort - input type="password"
  • Text - input type="text"

Zeichen Max

Maximale Länge der Eingabe (HTML attribute maxlength)

Vorschau

An dieser Stelle sehen Sie, wie das Erscheinungsbild entsprechend der vorherigen Einstellung der Zahlungsart Kreditkarte im Checkout aussieht.

 

Simple Protect

Simple Protect ist die einfache und flexible Art, alle Daten zu nutzen, die Sie haben, und zwar genau in dem Moment, in dem Ihr Shop den Checkout durchführt. Sie können z.B. Informationen von:

  • die Datenbank Ihres Magento 2 Shops
  • die aktuelle Checkout-Sitzung
  • externe Quellen, die vom Shopserver aus erreicht werden können (Datawarehouse; csv / xml / txt - Dateien, auf die mit PHP zugegriffen werden kann; APIs oder Erweiterungen wie die PAYONE Protect Funktionen und viele mehr.)

Im Folgenden finden Sie ein Beispiel für einige komplexe Entscheidungen, die mit Hilfe unseres simple protect framework getroffen werden können:

 

Simple Protect befindet sich derzeit im Beta-Stadium. Wenn Sie diese Funktionalität nutzen möchten, müssen Sie die PAYONE Integration aus dem Simple Protect-Zweig herunterladen:

https://github.com/PAYONE-GmbH/magento-2/tree/simple-protect

Danach folgen Sie bitte den Anweisungen zur Installation der Simple Protect-Vorlage hier:

https://github.com/PAYONE-GmbH/magento-2-simple-protect

Eine komplette Beispielimplementation finden Sie hier:

Bitte beachten Sie, dass alle im Legacy-Teil dieser Dokumentation beschriebenen Funktionen bei der Verwendung von simple protect nicht mehr zur Verfügung stehen. Zur Zeit bieten wir auch keinen Migrationsmechanismus an.
Bitte beachten Sie ebenfalls, dass Sie sich an die Richtlinien des GDPR halten müssen.

einbindung
1

Schritt eins, die Initialisierung eines database objects:

/**
 * Database connection resource
 *
 * @var \Magento\Framework\App\ResourceConnection
 */
protected $databaseResource;
2

der Zusammenbau deselbigen

/**
 * Constructor
 *
 * @param \Magento\Framework\App\ResourceConnection $resource
 */
public function __construct(
    \Magento\Framework\App\ResourceConnection $resource
)
{

    $this->databaseResource = $resource;
}
3

Danach können Sie die Datenbank nach Informationen wie den folgenden fragen

/**
 * Get count of customers orders
 *
 * @param CustomerInterface $oCustomer
 * @return int
 */
protected function getCustomersOrderCount(CustomerInterface $oCustomer)
{
    $db = $this->databaseResource->getConnection();
    $oSelect = $db->select()
        ->from($this->databaseResource->getTableName('sales_order'), ['COUNT(entity_id)'])
        ->where("customer_id = :customerId");
    $iCount = $db->fetchOne($oSelect, ['customerId' => $oCustomer->getId()]);
    if ($iCount === null) {
        return 0;
    }
    return $iCount;
}

Ausführung der payoNE protect checks

Um den PAYONE protect check ausführen zu können müssen Sie vorher den PAYONE prtectFunnel initieren und aufbauen

/**
 * PAYONE Protect model providing access to consumerscore and addresscheck requests
 *
 * @var \Payone\Core\Model\SimpleProtect\ProtectFunnel
 */
protected $protectFunnel;

public function __construct(
    \Payone\Core\Model\SimpleProtect\ProtectFunnel $protectFunnel
)
{
    $this->protectFunnel = $protectFunnel;
}
adressencheck

nachfolgend eine einfache Methode um einen Adresscheck der Rechnungsadresse auszuführen


/**
 * Example for addresscheck usage
 *
 * @param  Quote $oQuote
 * @return AddresscheckResponse|bool
 */
protected function executeAddresscheck(Quote $oQuote)
{
    $oAddress = $oQuote->getBillingAddress();
    $sAddresscheckType = AddressCheckType::BASIC;

    return $this->protectFunnel->executeAddresscheck($oAddress, $this->getOperationMode(), $sAddresscheckType);
}

Wenn Sie einen Adresscheck der Versandadresse durchführen möchten, müssen Sie die Variable $oAddress - wie folgt ändern

/**
 * getting the shipping address
 */
$oAddress = $oQuote->getShippingAddress();

Um den Adresscheck anderweitig zu nutzen haben Sie folgende Möglichkeiten

/**
 * Examples of all the types for addresscheck usage
 */
$sAddresscheckType = AddressCheckType::NONE;
$sAddresscheckType = AddressCheckType::BASIC;
$sAddresscheckType = AddressCheckType::PERSON;
$sAddresscheckType = AddressCheckType::BONIVERSUM_BASIC;
$sAddresscheckType = AddressCheckType::BONIVERSUM_BASIC;
consumerscore

Nachfolgend eine einfach Methode um den consumerscore abzufragen. Wie im Adresscheck beschrieben kann man auch die zu erfragende Adresse ändern

/**
 * getting the shipping address
 */
$oAddress = $oQuote->getShippingAddress();

Weitere Optionen für die consumerscore -Abfrage

/**
 * Examples of all the options for consumerscore usage
 */
$sConsumerscoreType = CreditratingCheckType::INFOSCORE_HARD;
$sConsumerscoreType = CreditratingCheckType::INFOSCORE_ALL;
$sConsumerscoreType = CreditratingCheckType::INFOSCORE_ALL_BONI;
$sConsumerscoreType = CreditratingCheckType::BONIVERSUM_VERITA;

Ein Beispiel

/**
 * Example for consumerscore usage
 *
 * @param  Quote $oQuote
 * @return ConsumerscoreResponse|bool
 */
protected function executeConsumerscore(Quote $oQuote)
{
    $oAddress = $oQuote->getBillingAddress();
    $sConsumerscoreType = CreditratingCheckType::INFOSCORE_ALL;

    return $this->protectFunnel->executeConsumerscore($oAddress, $this->getOperationMode(), $sConsumerscoreType, $sAddresscheckType);
}

Oben erlangtes Ergebnis können Sie wie folgt verwenden

/**
 * Check the result of executing the consumerscore
 * @return bool
 */
$oResponse = $this->executeConsumerscore($oQuote);
if ($oResponse instanceof ConsumerscoreResponse && ($oResponse->getStatus() != 'VALID' || $oResponse->getScore() != 'G')) {
    return true;
}

Im oben genannten Beispiel der Aufruf $oResponse->getScore() gibt Ihnen den Scorewert wie hier beschrieben zurück.

Filter Im store view

Wenn Sie noch weitere Entscheidungen im Store View treffen wollen, können Sie mit weiteren Magento Objekten danach fragen

/**
 * Change AddressCheckType for the stores
 * @default AddressCheckType::NONE
 */
$sAddresscheckType = AddressCheckType::NONE;
if ($oQuote->getStore()->getName() == 'new Brands') {
    $sAddresscheckType = AddressCheckType::PERSON;
} else if ($oQuote->getStore()->getCode() == 'old_Brands') {
    $sAddresscheckType = AddressCheckType::BASIC;
}

Konfiguration

Klicken Sie unter PAYONE → Protect

Diese Option betrifft nur Anfragen bezüglich der PAYONE - API wie adresscheck oder consumerscore. Sonstiger Code wird wie entwickelt ausgeführt.
Entry points / Points of action

Die Klasse app/code/Payone/SimpleProtect/Model/SimpleProtect/SimpleProtect.php ist der zentrale Punkt zur Umsetzung der Entscheidungen.

Die folgenden Methoden geben die Punkte wieder, an denen die Aktionen stattfinden.

Beispiel einer kompletten Integration
<?php

/**
 * PAYONE Magento 2 Connector is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * PAYONE Magento 2 Connector is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with PAYONE Magento 2 Connector. If not, see <http://www.gnu.org/licenses/>.
 *
 * PHP version 5
 *
 * @category  Payone
 * @package   Payone_Magento2_SimpleProtect
 * @author    FATCHIP GmbH <support@fatchip.de>
 * @copyright 2003 - 2019 Payone GmbH
 * @license   <http://www.gnu.org/licenses/> GNU Lesser General Public License
 * @link      http://www.payone.de
 */

namespace Payone\SimpleProtect\Model\SimpleProtect;

use Magento\Payment\Model\MethodInterface;
use Magento\Quote\Model\Quote;
use Payone\Core\Model\SimpleProtect\SimpleProtect as OrigSimpleProtect;
use Payone\Core\Model\PayoneConfig;
use Magento\Customer\Api\Data\CustomerInterface;
use Magento\Quote\Model\Quote\Address;
use Payone\Core\Model\Source\AddressCheckType;
use Payone\Core\Model\Source\CreditratingCheckType;
use Magento\Framework\Exception\LocalizedException;
use Payone\Core\Model\Exception\FilterMethodListException;
use Payone\Core\Model\Api\Response\AddresscheckResponse;
use Payone\Core\Model\Api\Response\ConsumerscoreResponse;
use Magento\Quote\Api\Data\AddressInterface;
use Magento\Store\Model\ScopeInterface;

class SimpleProtect extends OrigSimpleProtect
{
    const MODULE_VERSION = '1.0.0';

    /**
     * Whitelist of safe payment methods
     *
     * @var array
     */
    protected $safePaymentMethods = [
        PayoneConfig::METHOD_ADVANCE_PAYMENT,
        PayoneConfig::METHOD_CREDITCARD,
        PayoneConfig::METHOD_PAYPAL
    ];

    /**
     * PAYONE Protect model providing access to consumerscore and addresscheck requests
     *
     * @var \Payone\Core\Model\SimpleProtect\ProtectFunnel
     */
    protected $protectFunnel;

    /**
     * Database connection resource
     *
     * @var \Magento\Framework\App\ResourceConnection
     */
    protected $databaseResource;

    /**
     * Checkout session object
     *
     * @var \Magento\Checkout\Model\Session\Proxy
     */
    protected $checkoutSession;

    /**
     * Scope config object
     *
     * @var \Magento\Framework\App\Config\ScopeConfigInterface
     */
    protected $scopeConfig;

    /**
     * Constructor
     *
     * @param \Payone\Core\Model\SimpleProtect\ProtectFunnel     $protectFunnel
     * @param \Magento\Framework\App\ResourceConnection          $resource
     * @param \Magento\Checkout\Model\Session\Proxy              $checkoutSession
     * @param \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig
     */
    public function __construct(
        \Payone\Core\Model\SimpleProtect\ProtectFunnel $protectFunnel,
        \Magento\Framework\App\ResourceConnection $resource,
        \Magento\Checkout\Model\Session\Proxy $checkoutSession,
        \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig
    ) {
        parent::__construct($protectFunnel);
        $this->databaseResource = $resource;
        $this->checkoutSession = $checkoutSession;
        $this->scopeConfig = $scopeConfig;
    }

    /**
     * Returns configured operation mode used for the addresscheck and consumerscore
     *
     * @return string
     */
    public function getOperationMode()
    {
        return $this->scopeConfig->getValue('payone_general/global/protect_mode', ScopeInterface::SCOPE_STORES);
    }

    /**
     * Get count of customers orders
     *
     * @param CustomerInterface $oCustomer
     * @return int
     */
    protected function getCustomersOrderCount(CustomerInterface $oCustomer)
    {
        $db = $this->databaseResource->getConnection();
        $oSelect = $db->select()
            ->from($this->databaseResource->getTableName('sales_order'), ['COUNT(entity_id)'])
            ->where("customer_id = :customerId");
        $iCount = $db->fetchOne($oSelect, ['customerId' => $oCustomer->getId()]);
        if ($iCount === null) {
            return 0;
        }
        return $iCount;
    }

    /**
     * Check if the customer has ordered before
     *
     * @param CustomerInterface $oCustomer
     * @return bool
     */
    protected function isRecurringCustomer(CustomerInterface $oCustomer)
    {
        if ($this->getCustomersOrderCount($oCustomer) == 0) {
            return false;
        }
        return true;
    }

    /**
     * Possibility to whiteliste customers with custom functionality
     *
     * @param  CustomerInterface $oCustomer
     * @return bool
     */
    protected function isCustomerWhitelisted(CustomerInterface $oCustomer)
    {
        return true; // implement this for yourself or remove completely
    }

    /**
     * Generate hash of given address for comparison
     *
     * @param  Address $oAddress
     * @return string
     */
    protected function getAddressHash(Address $oAddress) {
        $sAddress  = $oAddress->getFirstname();
        $sAddress .= $oAddress->getLastname();
        $sAddress .= $oAddress->getCity();
        $sAddress .= $oAddress->getPostcode();
        $sAddress .= $oAddress->getCountry();
        $sAddress .= $oAddress->getStreetFull();

        return md5($sAddress);
    }

    /**
     * Compare given addresses, return true if they are the same
     *
     * @param  Address $oBilling
     * @param  Address $oShipping
     * @return bool
     */
    protected function isBillingAndShippingAddressTheSame(Address $oBilling, Address $oShipping)
    {
        if ($this->getAddressHash($oBilling) != $this->getAddressHash($oShipping)) {
            return false;
        }
        return true;
    }

    /**
     * Filter out all payment methods except for the safe payment methods
     *
     * @param  MethodInterface[] $aPaymentMethods
     * @return MethodInterface[]
     */
    protected function getSafePaymentMethods($aPaymentMethods)
    {
        $aReturn = [];
        foreach ($aPaymentMethods as $oPaymentMethod) {
            if (in_array($oPaymentMethod->getCode(), $this->safePaymentMethods) === true) {
                $aReturn[] = $oPaymentMethod;
            }
        }
        return $aReturn;
    }

    /**
     * Examples of all the options for addresscheck usage
     *
     * @param  Quote $oQuote
     * @return AddresscheckResponse|bool
     */
    protected function executeAddresscheck(Quote $oQuote)
    {
        $oAddress = $oQuote->getBillingAddress();
        #$oAddress = $oQuote->getShippingAddress();

        #$sAddresscheckType = AddressCheckType::NONE;
        $sAddresscheckType = AddressCheckType::BASIC;
        #$sAddresscheckType = AddressCheckType::PERSON;
        #$sAddresscheckType = AddressCheckType::BONIVERSUM_BASIC;
        #$sAddresscheckType = AddressCheckType::BONIVERSUM_PERSON;

        return $this->protectFunnel->executeAddresscheck($oAddress, $this->getOperationMode(), $sAddresscheckType, $this->getModuleVersion());
    }

    /**
     * Examples of all the options for consumerscore usage
     *
     * @param  Quote $oQuote
     * @return ConsumerscoreResponse|bool
     */
    protected function executeConsumerscore(Quote $oQuote)
    {
        $oAddress = $oQuote->getBillingAddress();
        #$oAddress = $oQuote->getShippingAddress();

        #$sConsumerscoreType = CreditratingCheckType::INFOSCORE_HARD;
        $sConsumerscoreType = CreditratingCheckType::INFOSCORE_ALL;
        #$sConsumerscoreType = CreditratingCheckType::INFOSCORE_ALL_BONI;
        #$sConsumerscoreType = CreditratingCheckType::BONIVERSUM_VERITA;

        $sAddresscheckType = AddressCheckType::NONE;
        #$sAddresscheckType = AddressCheckType::BASIC;
        #$sAddresscheckType = AddressCheckType::PERSON;
        #$sAddresscheckType = AddressCheckType::BONIVERSUM_BASIC;
        #$sAddresscheckType = AddressCheckType::BONIVERSUM_PERSON;

        return $this->protectFunnel->executeConsumerscore($oAddress, $this->getOperationMode(), $sConsumerscoreType, $sAddresscheckType, $this->getModuleVersion());
    }

    /**
     * Check rules for recurring registered customers
     *
     * @param  Quote $oQuote
     * @return bool
     */
    protected function isOnlySafePaymentApplicableForRecurringCustomer(Quote $oQuote)
    {
        if ($oQuote->getBaseGrandTotal() > 400 || $this->isCustomerWhitelisted($oQuote->getCustomer()) === false) {
            return true;
        }
        return false;
    }

    /**
     * Check rules for first time registered customer
     *
     * @param  Quote $oQuote
     * @param  bool  $blIsPrePaymentSelection
     * @return bool
     */
    protected function isOnlySafePaymentApplicableForInitialOrder(Quote $oQuote, $blIsPrePaymentSelection)
    {
        if ($blIsPrePaymentSelection === false && $this->isBillingAndShippingAddressTheSame($oQuote->getBillingAddress(), $oQuote->getShippingAddress()) === false) {
            return true;
        }

        if ($oQuote->getBaseGrandTotal() > 120) {
            return true;
        }

        if ($blIsPrePaymentSelection === false && !in_array($oQuote->getPayment()->getMethodInstance()->getCode(), $this->safePaymentMethods)) {
            $oResponse = $this->executeConsumerscore($oQuote);
            if ($oResponse instanceof ConsumerscoreResponse && ($oResponse->getStatus() != 'VALID' || $oResponse->getScore() != 'G')) {
                return true;
            }
        }
        return false;
    }

    /**
     * Check if only safe payment methods are applicable
     *
     * @param  Quote $oQuote
     * @param  bool  $blIsPrePaymentSelection
     * @return bool
     */
    protected function isOnlySafePaymentApplicable(Quote $oQuote, $blIsPrePaymentSelection)
    {
        if ($this->checkoutSession->getPayoneSimpleProtectOnlySafePaymentsAllowed() === true) {
            return true;
        }

        if ($oQuote->getCustomerId() === null) { // if guest checkout
            return true;
        }

        if ($this->isRecurringCustomer($oQuote->getCustomer()) === true) {
            return $this->isOnlySafePaymentApplicableForRecurringCustomer($oQuote);
        }
        return $this->isOnlySafePaymentApplicableForInitialOrder($oQuote, $blIsPrePaymentSelection);
    }

    /************************* MAIN SIMPLEPROTECT HOOKS *************************/

    /**
     * This method can be extended for individual custom behaviour
     *
     * Extending this method gives the following possibilities:
     * 1. Filtering out payment methods based on your own rule set
     * 2. Throwing a LocalizedException to send the user back to shipping method selection
     *
     * @param  Quote             $oQuote
     * @param  MethodInterface[] $aPaymentMethods
     * @return MethodInterface[]
     */
    public function handlePrePaymentSelection(Quote $oQuote, $aPaymentMethods)
    {
        if ($this->isOnlySafePaymentApplicable($oQuote, true) === true) {
            return $this->getSafePaymentMethods($aPaymentMethods);
        }
        return $aPaymentMethods;
    }

    /**
     * This method can be extended for individual custom behaviour
     *
     * Extending this method gives the following possibilities:
     * 1. Throwing a LocalizedException will stop the order creation and throw the user back to payment selection with the given thrown message
     * 2. Throwing a FilterMethodListException with an array of safe payment methods will stop the order creation and
     *    throw the user back to payment selection with the given thrown message and remove all other payment methods except for the given ones
     * 3. Finishing the method - so throwing no Exception will finish the order creation
     *
     * @param  Quote $oQuote
     * @return void
     * @throws LocalizedException
     * @throws FilterMethodListException
     */
    public function handlePostPaymentSelection(Quote $oQuote)
    {
        if ($this->isOnlySafePaymentApplicable($oQuote, false) === true) {
            $sMethodCode = $oQuote->getPayment()->getMethodInstance()->getCode();
            if (!in_array($sMethodCode, $this->safePaymentMethods)) {
                $this->checkoutSession->setPayoneSimpleProtectOnlySafePaymentsAllowed(true);
                throw new FilterMethodListException(__('Please select another payment method.'), $this->safePaymentMethods);
            }
        }
    }

    /**
     * This method can be extended to transfer the version of your Simple-Protect implementation to Payone
     * It is recommended to transfer the name of your module and the version, otherwise Payone doesn't know that it is a Simple-Protect call
     *
     * @return string|null
     */
    public function getModuleVersion()
    {
        return 'Payone_SimpleProtect-'.self::MODULE_VERSION;
    }
}

Wir haben weitere Beispiele unter Magento 2 - Simple Protect zusammengestellt. Hier finden Sie weitere Informationen darüber, wie Sie Daten für Ihre Entscheidungen gewinnen können. Sie sind auch eingeladen, weitere Beispiele als Themen auf Github oder per E-Mail an docs@payone.com hinzuzufügen.
handlePrePaymentSelection

Die Umsetzung dieser Methode bietet Ihnen folgende Möglichkeiten:

  1. Das Auslösen einer LocalizedException stoppt die Auftragserstellung und wirft den Benutzer mit der angegebenen Meldung zurück zur Zahlungsauswahl
  2. Das Auslösen einer FilterMethodListException mit einem Array von sicheren Zahlungsmethoden stoppt die Auftragserstellung und wirft den Benutzer mit der angegebenen Meldung zurück zur Zahlungsauswahl und entfernt alle anderen Zahlungsmethoden außer den angegebenen
  3. Beenden der Methode - also keine Exception auslösen, beendet die Auftragserstellung
handlePrePaymentSelection
@param  Quote $oQuote
@param  MethodInterface[] $aPaymentMethods
@return MethodInterface[]

public function handlePrePaymentSelection(Quote $oQuote, $aPaymentMethods)
{
    if ($this->isOnlySafePaymentApplicable($oQuote, true) === true) {
        return $this->getSafePaymentMethods($aPaymentMethods);
    }
    return $aPaymentMethods;
}

handlePostPaymentSelection

Die Umsetzung dieser Methode bietet Ihnen folgende Möglichkeiten:

  1. Das Auslösen einer LocalizedException stoppt die Auftragserstellung und wirft den Benutzer mit der angegebenen Meldung zurück zur Zahlungsauswahl
  2. Das Auslösen einer FilterMethodListException mit einem Array von sicheren Zahlungsmethoden stoppt die Auftragserstellung und wirft den Benutzer mit der angegebenen Meldung zurück zur Zahlungsauswahl und entfernt alle anderen Zahlungsmethoden außer den angegebenen
  3. Beenden der Methode - also keine Exception auslösen, beendet die Auftragserstellung
handlePostPaymentSelection
@param  Quote $oQuote
@return void
@throws LocalizedException
@throws FilterMethodListException

public function handlePostPaymentSelection(Quote $oQuote)
{
    if ($this->isOnlySafePaymentApplicable($oQuote, false) === true) {
        $sMethodCode = $oQuote->getPayment()->getMethodInstance()->getCode();
        if (!in_array($sMethodCode, $this->safePaymentMethods)) {
            $this->checkoutSession->setPayoneSimpleProtectOnlySafePaymentsAllowed(true);
            throw new FilterMethodListException(__('Please select another payment method.'), $this->safePaymentMethods);
        }
    }
}
handleEnterOrChangeBillingAddress

Die Umsetzung dieser Methode bietet Ihnen folgende Möglichkeiten:

  1. Wenn true zurückgegeben wird, wird der Prozess fortgesetzt, ohne dass etwas geändert wird.
  2. Die Rückgabe einer (geänderten) Adressobjektinstanz von AddressInterface zeigt dem Kunden eine Aufforderung zur Adresskorrektur
  3. Das Auslösen einer LocalizedException zeigt dem Kunden die angegebene Ausnahmemeldung an
handleEnterOrChangeBillingAddress
@param AddressInterface $oAddressData
@param bool $blIsVirtual
@param double $dTotal
@return AddressInterface|bool
@throws LocalizedException

public function handleEnterOrChangeBillingAddress(AddressInterface $oAddressData, $blIsVirtual, $dTotal)
    {
        $response = $this->protectFunnel->executeAddresscheck($oAddressData, $this->getOperationMode(), AddressCheckType::BASIC);
        if ($oAddressData->getCity() == "FalscheStadt") {
            $oAddressData->setCity($response->getCity());
            return $oAddressData;
        }
        return true;
    }

handleEnterOrChangeShippingAddress

Die Umsetzung dieser Methode bietet Ihnen folgende Möglichkeiten:

  1. Wenn true zurückgegeben wird, wird der Prozess fortgesetzt, ohne dass etwas geändert wird.
  2. Die Rückgabe einer (geänderten) Adressobjektinstanz von AddressInterface zeigt dem Kunden eine Aufforderung zur Adresskorrektur
  3. Das Auslösen einer LocalizedException zeigt dem Kunden die angegebene Ausnahmemeldung an
handleEnterOrChangeShippingAddress
@param AddressInterface $oAddressData
@param bool $blIsVirtual
@param double $dTotal
@return AddressInterface|bool
@throws LocalizedException

public function handleEnterOrChangeShippingAddress(AddressInterface $oAddressData, $blIsVirtual, $dTotal)
    {
        $response = $this->protectFunnel->executeAddresscheck($oAddressData, $this->getOperationMode(), AddressCheckType::BASIC);
        if ($oAddressData->getCity() == "FalscheStadt") {
            $oAddressData->setCity($response->getCity());
            return $oAddressData;
        }
        return true;
    }

Protect (Legacy)

Klicken Sie unter PAYONE → Protect

Adressprüfung

Feld Beschreibung

Aktiviert

Aktiviert die Adressprüfung

Betriebsmodus

Hier wird bestimmt, ob die PAYONE Plattform im Test- oder Live-Modus angesprochen wird.

Prüfe Rechnungsadresse

Konfiguration, mit welcher Prüfung die Rechnungsadresse geprüft werden soll.

Prüfe Lieferadresse

Konfiguration, mit welcher Prüfung die Lieferadresse geprüft werden soll.

Prüfe Rechnungsadresse für virtuelle Bestellungen

Wählen Sie, ob die Rechnungsadresse bei virtuellen Bestellungen geprüft werden soll.

Bestätigung der Adresskorrektur

Auswahl, ob eine Adresskorrektur vom Käufer bestätigt werden muss.

Meldung bei ungültigen Daten

Tragen Sie hier die Fehlermeldung ein, die beim Status "INVALID" angezeigt werden soll.

Behandlung von Fehlern

Was soll nach einem Fehler in der Extension oder der PAYONE Plattform ausgeführt werden?

Minimaler Warenwert

Mindestbetrag für die Durchführung einer Adressprüfung.

Maximaler Warenwert

Maximalbetrag für die Durchführung einer Adressprüfung

Gültigkeit

Anzahl der Tage, an denen keine neue Adressüberprüfung durchgeführt wird.

Bonitätsprüfung

Feld Beschreibung

Aktiviert

Aktiviert die Bonitätsprüfung

Betriebsmodus

Hier wird bestimmt, ob die PAYONE Plattform im Test- oder Live-Modus angesprochen wird.

Zeitpunkt der Prüfung

Auswahl der "Vor/Nach der Zahlartenauswahl"

Bonitätscheck-Typ

  • Infoscore (Harte Merkmale, Alle Merkmale, Alle Merkmale + Boniscore)
  • Boniversum (VERITA Score)

Standardwert für unbekannte Scores

Auswahl einer Ampelfarbe für den Rückgabestatus "Unbekannt"

Das betrifft nur Prüfungsergebnisse bei Verwendung des Bonitätschecks 'Boniversum VERITA Score

Erlaubte Zahlarten bei Ampelwert "Gelb/Rot"

Mehrfachauswahl der zulässigen Zahlungsarten nach Ampelfarbe

Behandlung von Fehlern

Was ist zu tun, wenn ein Fehler in der Integration oder auf der PAYONE Plattform auftritt?

Insufficient score error message

Meldung, die dem Kunden angezeigt wird, wenn ein unzureichender Punktwert erreicht wird.

Minimaler Warenwert

Mindestbetrag für die Durchführung einer Adressprüfung.

Maximaler Warenwert

Maximalbetrag für die Durchführung einer Adressprüfung.

Gültigkeit

Anzahl der Tage, an denen keine neue Adressüberprüfung durchgeführt wird.

Dienstleister für Adress- und Bonitätsprüfung
Für die Adress- und Bonitätsprüfung stehen verschiedene Dienstleister zur Verfügung. Unser Support-Team erklärt Ihnen gerne, welchen Leistungsumfang die einzelnen Prüfungen haben und welcher Dienstleister für Sie der Richtige ist.

Liste mit PAYONE IP-Adressen

Klicken Sie unter PAYONE → Sonstiges

Nach der Installation sind dort die aktuell gültigen IP-Adressen angegeben, die einen Transaktionsstatus liefern dürfen. Ändern Sie diese nur bei Bedarf. Sie müssen diese Adressen nur dann hinzufügen, wenn Ihre Systemlandschaft z.B. mit Load Balancern oder Proxy-Systemen arbeitet.

Weiterleitung des Transaktionsstatus

Klicken Sie unter PAYONE → Sonstiges

An dieser Stelle können Sie festlegen, welcher Status an welche URL weitergeleitet wird und wie lange der Timeout in Sekunden ist, bis der Umleitungsversuch beendet wird.

Rechnungsinformationen

Klicken Sie unter PAYONE → Sonstiges

Rechnungsinformation - Rabatt

Hier können Sie eine SKU festlegen, die zur Identifizierung von Rabattartikeln verwendet werden soll. Dies kann leer gelassen werden, es sei denn, Sie haben Probleme mit Einkaufswagenartikeln.

Rechnungsinformation - Versandkosten

Hier können Sie eine SKU festlegen, die zur Identifizierung von Versandartikeln verwendet werden soll. Dies kann leer gelassen werden, es sei denn, Sie haben Probleme mit Einkaufswagenartikeln.

Rechnungsinformation - Gutschein

Hier können Sie eine SKU angeben, die zur Identifizierung von Gutscheinen verwendet werden soll. Dies kann leer gelassen werden, es sei denn, Sie haben Probleme mit Einkaufswagenartikeln.

Konfiguration exportieren

Klicken Sie unter PAYONE → Konfiguration exportieren

Mit dem Klick auf Konfiguration exportieren wird eine Datei heruntergeladen.

Sie können diese Datei nun mit einem XML-Editor öffnen, ansehen oder speichern. Dieser Export ist für jede Support-Anfrage an das PAYONE Team sehr wichtig, um mögliche Konfigurationsprobleme zu vermeiden. Anhand dieser Datei kann auch festgestellt werden, ob weitere Erweiterungen installiert wurden, die Kompatibilitätsprobleme verursachen könnten.

PAYONE Logs

Klicken Sie unter PAYONE → Protokolle

Unter dem Punkt Protokolle finden Sie alle Informationen über die abgewickelten Zahlungen und die Kommunikation mit der PAYONE Plattform.

API Logs

In dieser Übersicht finden Sie alle Anfragen des Magento Shops an die PAYONE Plattform sowie die Antworten der PAYONE Plattform auf diese Anfragen. Lediglich die Anfragen, die über die Client API an die PAYONE Plattform übermittelt wurden, sind in dieser Übersicht nicht aufgeführt. Dies gilt für Kreditkarteninformationen, die mittels Ajax-Technologie direkt vom Browser des Käufers an die PAYONE Plattform übertragen werden, so dass Ihr Shop nicht mit sensiblen Kreditkarteninformationen in Berührung kommt. Mit einem Klick auf Ansicht können Sie sich eine API-Anfrage im Detail anzeigen lassen.

In der linken Spalte sehen Sie die Anfrage, die der Magento-Shop an die PAYONE Plattform gesendet hat. Auf der rechten Seite finden Sie die Antwort. Eine detaillierte Erklärung der jeweiligen Parameter finden Sie in der technischen Dokumentation der PAYONE Plattform im PAYONE Merchant Interface (PMI) unter Downloads → Dokumentation.

Transaktionsstatus Logs

Klicken Sie unter PAYONE → Transaktionsstatus

Der Unterpunkt Transaktionen zeigt die von Magento empfangenen Benachrichtigungen über den Transaktionsstatus für jede Bestellung und Transaktion an. Diese Benachrichtigungen werden von der PAYONE Plattform an Ihren Shop gesendet. Im Fehlerfall können Sie hier erfahren, ob der Transaktionsstatus korrekt empfangen wurde und wie der aktuelle Status einer Transaktion ist. Mit einem Klick auf Ansicht können Sie sich Details zu einem Transaktionsstatus anzeigen lassen.

Auf der Detailseite sehen Sie alle Informationen zum Transaktionsstatus, die über die PAYONE Plattform an Ihren Shop übermittelt werden. So können Sie jederzeit nachvollziehen, welche Daten Ihr Magento-Shop erhalten und verarbeitet hat.

Eine detaillierte Erklärung der jeweiligen Parameter finden Sie in der technischen Dokumentation der PAYONE Plattform im PAYONE Merchant Interface (PMI) unter Downloads → Dokumentation.