Integration Guide Magento 1

Introduction

Magento 1 has reached its end-of-life phase!

We'll continue supporting our Magento 1 plugin for the time being.

However, using out-of-date software is a potential security thread for your and your customers' data. PCI DSS even requires merchants to keep their stores up to date. If you plan on keeping both Magento 1 and your PCI DSS compliance, we recommend looking into initiatives like https://www.openmage.org/ or https://mage-one.com/

Offers the following payment methods:

  • Credit Cards (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 Secure Invoice
  • PAYONE Secured Invoice, secured Direct Debit und secured Installments
  • PAYONE Direct Debit
  • PAYONE Open Invoice
  • PAYONE Prepayment
  • PayPal und PayPal Express
  • PostFinance Card and E-Finance
  • Przelewy24
  • Sofort
  • Ratepay Invoice, Direct Debit and Installments
  • Trustly
  • Unzer Invoice, Direct Debit and Installments
  • WeChat Pay

Keep an eye on our Release Notes to stay informed about updates and new features (i.e. payment methods, features, integration modes) we have added to this plugin!

Check out our documentation to learn how to link your store with our platform to profit from all these features!

Current Release: v5.3.2

Requirements

An active PAYONE - Account is required. If you do not have one yet, please contact us.

Plugin Installation

Your way to install our plugin:


Installation via Github

PAYONE - Portal configuration

To send the transaction status to the correct address, the log in to the PAYONE Merchant Interface (PMI).

Under Configuration → Payment Portals → YOUR_PORTAL → Advanced → TransactionStatus URL

<SHOPURL>/index.php/payone_core/transactionStatus

Please leave the hash check set to "md5 oder sha2-384 (during migration)" to ensure correct communication between PAYONE and the store.
Additional Response-data

Under General, set the Additional Response data for both Live and Test modes to "on".

Magento 1 - Admin configuration

PAYONE → Configuration → General

Please enter your access data from the PMI here:
 

Here you can make further settings

Detailed description of each field

Field Description
Merchant ID You will find your PAYONE Merchant ID at the top right of the PAYONE Merchant Interface (PMI) and on all PAYONE invoices.
Portal ID You can find the portal ID in the PAYONE Merchant Interface (PMI) under the menu item Configuration → Payment Portals

Sub-Account-ID

You can find the ID in the PAYONE Merchant Interface (PMI) under the menu item Configuration → Accounts

Security-Key

Please enter the key here to protect the data communication against manipulation. This must be identical to the key stored in the corresponding PAYONE payment portal.

Payment from Applicable countries

Selection option for the shop in which countries payment via PAYONE is to be made possible.

Authorize-Method

  • preauthorisation - The amount to be paid is reserved in the course of the order. In this case, the debit must be initiated in a second step when the goods are delivered (Capture). The receivable is only posted after the capture has been carried out.
  • authorisation - The amount tobe paid is collected immediately when the order is placed. The receivable is immediately booked on the PAYONE platform.

Transfer IP address

Select whether the IP address of the end customer should be transmitted to the PAYONE platform. Currently the PAYONE platform only supports IPv4. If your hoster supports IPv6, you should deactivate this setting, otherwise rejected transactions may occur. In this case a check of the IP address is not possible.

proxy mode

Activate this option to transfer the IP from the HTTP_X_FORWARDED_FOR header. This is only necessary if your shop is running behind a proxy server.

Currency

Here you can select whether requests are sent to the PAYONE platform in the selected currency, or whether the amounts should be converted Magento internally into a base currency beforehand.

Payment methods setup

PAYONE → Configuration → Payment methods

Overview

All PAYONE payment types created are displayed in this overview. Using the buttons at the top you can add and configure further payment methods. The Edit link can be used to configure each individual payment type specifically. Please note that you should only configure the payment methods that you have ordered from PAYONE.

Add/ Edit Payment Method

Detailed description of each field

Field Description

Enabled

Determines whether the payment method is available in the checkout process.

Sort order

Enter an integer that determines where in the checkout the payment method is offered to the customer.

Name

Free text entry for the name of the payment method as it is displayed to the customer in the checkout.

Handling Fee

Determination of a handling fee per shipping method and associated countries.

Minimum Order Total

The minimum value of goods from which the payment type is displayed to the customer in the checkout e.g. 100 = 100 EUR

Maximum Order Total

The maximum value of goods up to which the payment method is displayed to the customer in the checkout e.g. 100 = 100 EUR

Mode

Here you can specify for the respective payment type whether the payments are to be processed in test mode or whether they are to be executed "live". You can also configure the test mode for individual payment types.

Use Global Settings

Select Yes / No. If No is selected, all parameters from the global settings can be configured individually for this payment method. The documentation of these settings can be found under point 4.2.2.

Special adjustments

Some payment methods require special adjustments. The next points are only relevant to you if you use the specific payment method:

PAYONE Secure Invoice

This payment method requires a separate payment portal. Please click on No under PAYONE → Configuration → Payment-Methods → Invoice with Payment Guarantee → Use global settings and enter a separate portal ID under Portal ID.

PayPal

Field Description

PayPal Express Checkout Shortcut on Shopping Cart

Activates the PayPal ECS button in the shopping cart for checkout

Paypal Express Image Button

Here you can upload the corresponding logo for the StoreView.

In order to use PayPal ECS correctly, it is necessary to have activated the module included in the Magento standard for PayPal.

 

Ratepay
Field Description

Display detailed error messages

Here you can select whether, in the case of rejection, the error message transferred by RatePay should be displayed, for example, that the transaction could not be executed due to the credit check, or whether a generic error message should be displayed.

RatePay Shop IDs 

RatePay requires the transfer of a so-called Shop-ID, which identifies the parameters of the shop. Enter the shop IDs received from RatePay and the corresponding currency in ISO 4217 format (e.g. EUR, USD, DKK). When saving the configuration, the parameters are queried at RatePay and transferred to the configuration.

Device Fingerprint Snippet ID

If you have been given a custom device fingerprint snippet ID by Ratepay, you can configure it under PAYONE → Configuration → General (at the bottom of the page). The default value is "ratepay".

 

RatePay Goodwill Refunds

When using Adjustment Refunds with RatePay transactions, please make sure to set the quantity of all items to 0 in order to successfully trigger the generic refund.

 

Amazon Pay

Integration Settings in Seller Central

Please enter the following URL under Integrator-URL in the item "Integration settings" in Seller Central: https://gpc-sys.pay1.de/gpc/amazon/1.0/notify - the "Seller URL" may remain empty. This URL ensures that the shop receives all notifications from Amazon.

Also please make sure to store all your shop URLs as allowed Javascript Origin in Seller Central.
  1. From the Seller Central home page, select “Integration - Integration Central” from the navigation bar on top-left side
  2. From Integration Central page, scroll down to the “Manage client ID/store ID(s)” section, and click “View client ID/store ID(s)”
  3. If you have an existing client or Store ID registered, review the configuration of the selected store. You can click on the “Edit” link on the right side to edit information
  4. If you click on the “Edit” button, you can edit all the details of the client configuration
  5. From STEP 3, if you click on the “Create new configuration” link on top, you will be able to create a new client configuration providing all the relevant information

Retrieve Configuration in Magento Backend

To activate the payment method, please use the "get configuration" button. This retrieves your client ID and Seller ID from our Platform. You should then see the values in the corresponding fields.

ACTIVATE THE PAYMENT METHOD

Please note that you can only make live payments if the payment method is approved for live payments in Seller Central.

 

Field Description

Client ID & Seller ID
 

These fields contain the Client ID and Seller ID as stored by the Merchant Service on the PAYONE platform after completion of the configuration.

You must first make all other settings and save the payment method Amazon Pay once before you can retrieve these values via the "Get Configuration" button!

JavaScript Origin & Return URL

The URLs in these fields are for your information. They must be deposited in the Amazon Seller Central, otherwise Amazon will reject the login requests.

Button Type, Color, Language

Here you can select the type of button, the color and the language for the Amazon Pay Button. The recommended settings are already selected as default.

Amazon mode

Amazon Pay supports two basic operating modes:

  • Synchronous - An attempt is made to obtain a direct (synchronous) confirmation for the Amazon Pay payment request. It may be that Amazon Pay refuses a payment request because a longer check would be necessary.
  • Asynchronous - Amazon Pay checks the payment over a longer period of time. The payment is accepted or rejected later (asynchronously).

In the PAYONE Plugin for Magento, this results in two operating modes:

  • Always synchronous - There is always an attempt to obtain a synchronous confirmation for the Amazon Pay payment request. An asynchronous payment request does not take place.
  • Asynchronous on error - A synchronous payment request is first attempted. If this is rejected by Amazon Pay, an asynchronous payment request is attempted, which has a higher chance of success. Only if this was also rejected, the buyer will be returned accordingly.

In some cases there can be an interference between our plugin and the Amazon plugin provided in the Magento Core. So if you encounter "strange behavior" like disapperaing amazon buttons, you could try the following command in the magento root:

Root Befehl
php bin/magento module:disable Amazon_Payment

Troubleshooting Amazon Pay Issues

In rare cases Amazon Pay transactions can break due to rounding differences during the last checkout step. In version 4.6.0 of our plugin we introduced the following switch under PAYONE → Configuration → General

 

This switch can help mitigate such rounding difference issues. We recommend leaving it on off though if you don't experience any Amazon Pay issues.

Creditcard

Field Description

Creditcard-Type

Multiple selection. Which credit card brands should be offered in the frontend?

Hide Card Validation Code

hides the verification number for cards that do not offer it

Check Card Validation Code

  • No
  • First order with card
  • Always
Determines whether the credit card verification number is queried. This is only possible if the acquirer allows it

Save payment data for logged in users

Here you can specify whether the pseudo credit card data should be saved for registered users so that the user does not have to enter his credit card number again when ordering again. The actual credit card data is only stored with PAYONE.

PAYONE Direct debit

Field Description

Validate bank code

Determines whether an additional check of the bank details is to be carried out.

List of supported SEPA countries

Multiple selection of the countries from which the payment type debit memo is supported. The PAYONE platform currently only supports direct debits for German bank accounts.

Show additional account number/bank code number

Legacy option from the transition period from account number to IBAN. Please choose NO.

Mandate enabled

Select Yes / No. Should the SEPA mandate manager be used? A check of the bank details is obligatory. A check against the POS lock list is not possible.

Mandate download enabled

Here you can define whether the buyer receives a download of the mandate from PAYONE at the end of the checkout.

Save payment data for logged in customers

Here you can specify whether the IBAN and BIC of a logged in user should be saved so that they do not have to be entered again when a new order is placed. The account connection is stored encrypted in the Magento database.

Apple Pay

Field Description

Merchant ID

This value can be taken from the Apple Developer Portal as "Identifier" of your Merchant ID:

Merchant Identification Certificate file

Please upload the merchant_id.perm file. You can find the file in the Apple Developer Portal.

Certificate private key

Please upload the merchant_id.key file. You can find the file in the Apple Developer Portal.

Certificate key password

Here you can set the password for using the private key

Creditcard-Type

Select here the card types that are allowed for Apple Pay. Please only select the card types here that are also part of your PAYONE contract.

In addition to the configuration in Magento, it is also necessary to set up the corresponding certificates to operate Apple Pay as a payment method. You can find instructions for this here: Special Remarks - Apple Pay

Additionally, Apple requires validation of the store domain for Apple Pay. To do this, follow the instructions in the Apple Developer Portal:

Unzer Payments

Field Description

Company Name

The full name of the company must appear here. The name will be used in the privacy policy.

Installment purchase Sample Username

In order to retrieve the installment purchase draft contract, the user name assigned by Unzer (usually dealer name installation) must be stored here.

Installment purchase Sample Password

The password assigned by Unzer must be stored here in order to retrieve the installment purchase draft contract.

B2B Mode

If the B2B mode is activated, it is automatically assumed that it is a B2B transaction if the "Company" field was executed during address entry. To check the creditworthiness of the company, further information such as the commercial register number is then requested in the checkout.

type

Multiple selection: Here you can select which payment methods of Unzer should be available to the buyer. You can choose between purchase on account, payment by instalments and direct debit.

Editing the orders

Click on PAYONE → Orders


Overview

Here you will find a PAYONE-specific order overview similar to the Magento order overview. In addition to the standard information, you can view the payment status on the PAYONE platform, the exact type of payment (e.g. credit card brands) and, if applicable, the dunning status. A click on View opens the detailed view of the corresponding order.

Capture

Preauthorized transactions have to be captured in order to trigger the actual cash flow. The PAYONE Plugin handles this step during creation of the invoice for a given order.

 

By selecting "Capture Online" in the drop-down shown above, the receivable is collected on the PAYONE platform. If you don't want to capture the money but still want to create an invoice and receivable, please use "Capture Offline" instead.

Partial captures are also possible by simply adjusting the invoicable quantity of items.

Refund

Already captured funds can be returned by creating a credit memo for an existing invoice.

Please ensure to create a credit memo within an invoice object, not in the order!
By selecting the "Refund" Button here, Money is sent back to the customer's payment method. "Refund Offline" will create the credit memo, but won't trigger any cash flow. Partial refunds are possible using the same method as with partial captures. You can also adjust the sum of the refund to account for fees during the refund, but keep in mind that some payment methods rely on cart items to match with the initial order.
Extended configurations

Here you will find separate setting options that allow you to customize our plugin more precisely to your needs.

Send invoicing information

Click on PAYONE → General → Send invoicing information activate the transmission of item data to create an invoice on the PAYONE platform.

The text can be freely selected and appears as dynamic text on the invoice or credit note. Various Magento variables can be used as placeholders.

 

Status Mapping

Click on PAYONE → Configration → General → Status Mapping the different transaction statuses of the PAYONE platform can be mapped to Magento order statuses. If a new transaction status is received, the corresponding "Magento status" is set in the order overview in the Magento backend. This can be entered separately for each payment type.

 

If you map the status "appointed" to "Payment Review", the PDF invoices will not be generated automatically. A different status should be selected here.

Creditcard - CSS adjustments

Our plugin offers you the conformity with the "lowest" Compliance Level according to PCI DSS (SAQ A). Since in this compliance level all credit card data may only be entered in fields hosted by a PCI DSS certified service provider, our extension uses iFrames that are integrated into the checkout. However, these do not inherit the CSS of the shop template, but contain their own style. You can use the following settings under PAYONE → Configuration → General → Credit Card Payment to customize these fields.

 

Field Description

Minimum Validity Period

Enter an integer in days. This value defines the number of days a credit card must be valid up to before it is rejected at checkout.

Request-type

  • hosted-iFrame
  • AJAX
Make sure to always use "hosted iFrame". Only merchants with a PCI DSS certification level of SAQ A-EP or greater are allowed to use AJAX. We still strogly suggest using hosted iFrame!

Input-configuration

Here you can set separate parameters for the individual fields of the credit card query.

Type

  • Numeric - Only numbers are allowed and for mobile devices the numeric keyboard is used input type="tel".
  • Passwort - input type="password"
  • Text - input type="text"

Digit count

Length of the field in characters (HTML attribute size)

Max-digits

Maximum length of input (HTML attribute maxlength)

IFrame

  • Standard - Uses width and height from standard style
  • Custom - Uses width and height from the following fields

width

CSS - Specify width

height

CSS - Indication of height

style

  • Standard - Uses CSS specification from Standard
  • Custom - Uses CSS specification from the following field

CSS

Specification of CSS properties for field

Deactivated with previous selection of Standard

Standard Style

fields

  • Input - CSS specification for all input fields (HTML input)
  • Selection - CSS specification for all selection fields (HTML select )

IFrame

  • Width - CSS specification
  • Height - CSS specification

Error-output

Language

Select the language in which the error message is to be output.

Activate automatic recognition of credit card number

determines whether the card number should be determined automatically when the first six digits are entered.

Preview

At this point you can see how the appearance looks according to the previous setting of the credit card payment method in Checkout.

Simple Protect

Simple Protect is the easy and flexible way of using all the data you have, right in the moment when your shop is proccessing the checkout. You can i.e. gain information from:

  • your magento 1 shop database
  • the current checkout session
  • external sources that can be reached and accessed from the shop server (datawarehouse; csv / xml / txt - files that can be accessed with PHP; APIs or extensions like the PAYONE Protect Functions and many more.)

Here is an example of some complex decisions that can be performed using our simple protect framework:

Simple Protect is currently under beta stage. If you want to use this functionality you have to download the PAYONE Integration from the Simple Protect branch:

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

After that, please follow the intructions for installing the Simple Protect Template here:

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

Please be aware that all functions described in the legacy part of this documentation won't be available anymore when using simple protect. For the time being, we also don't offer a migration mechanism.
Entry points / Points of action

The class app/code/Payone/SimpleProtect/Model/SimpleProtect/SimpleProtect.php is the central point to implement the decisions. The following methods reperesent the points where the actions are taking place.

The following methods show the points at which the actions take place.

 

Example of full implementation
<?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;
    }
}

We're curating more samples at Magento 2 - Simple Protect. Here you will find more information on how to gain data for your decisions. You're also invited to add more examples as issues on github or vial email at docs@payone.com.
handlePrePaymentSelection

Implementing this method gives you 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

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

Implementing this method gives you 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

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

Implementing this method gives you the following possibilities:

  1. Returning true will just continue the process without changing anything
  2. Returning a (changed) address object instance of AddressInterface will show an address correction prompt to the customer
  3. Throwing a LocalizedException will show the given exception message to the customer

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

Implementing this method gives you the following possibilities:

  1. Returning true will just continue the process without changing anything
  2. Returning a (changed) address object instance of AddressInterface will show an address correction prompt to the customer
  3. Throwing a LocalizedException will show the given exception message to the customer

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)

Click on PAYONE → Configuration → PROTECT

Address Validation

Field Description

Enabled

Selection Yes / No. Depending on the selection, the address check is carried out according to the settings.

Check billing address

Selection None / Basic / Person. Depending on the selection, the address is checked in the appropriate granularity.

Check delivery address

Selection None / Basic / Person. Depending on the selection, the address is checked in the appropriate granularity.

operating mode

Choice between Test / Live. This determines whether the PAYONE platform is addressed in Test or Live mode.

Confirming the address correction

Select Yes / No. This determines whether the buyer will be asked to confirm the correction when returning a corrected address.

Minimum value of goods

The minimum value of goods from which an address check is carried out.

Minimaler Warenwert

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

Maximum value of goods

The maximum value of goods up to which an address check is carried out.

person status mapping

When the address check is executed at person level, a traffic light value can be assigned for payment type selection, depending on the result of the person check.

Invalid data message

Free text field for entering the message that is displayed to the buyer in the checkout if he has not entered valid data.

error handling

Cancel selection of order / Continue order process. This determines whether the order process should still be carried out in the event of technical problems or missing entries.

validity

Enter an integer that determines how long the result of the address check is to be kept. No new check is carried out within this period.

Various service providers are available for address and creditworthiness checks. Our support team will be happy to explain the range of services of the individual checks and which service provider is the right one for you.
Credit Assessment

Field Description

Enabled

Select Yes / No. Determines whether the credit check is activated with the following settings.

Integration Event

  1. Before selecting the payment method
  2. After selecting the payment method - you can select the creditworthiness index for the payment type so that a check is only carried out for certain payment types.

Activated for the following payment types

Multiple selection of payment types that result in a credit check when selected.

Note text activated

Select Yes / No. Determines whether a text message is displayed to the buyer.

hint text

Free text field for specifying the note text.

customer approval

Select Yes / No. Determines whether the buyer is asked to perform a credit check. If the customer does not agree, an order is still possible.

Text of the consent query

Free text field for the approval query. Only displayed if customer approval is set to Yes.

Creditworthiness check type

Selection of whether hard/soft criteria and the boniscore value should be queried.

Permitted payment types for traffic light value "YELLOW

Multiple selection of the permitted payment types when the traffic light value YELLOW is returned.

Permitted payment types for traffic light value "RED".

Multiple selection of the permitted payment types when the traffic light value RED is returned.

Activate A/B test mode

Select Yes / No. Determines whether the credit assessment is to be carried out on a random basis.

Frequency of sampling

Enter an integer that defines the frequency of the creditworthiness checks performed in the sampling mode.

error handling

Cancel selection of order / Continue order process. This determines whether the order process should still be carried out in the event of technical problems or missing entries.

validity

Input of an integer that determines how long the result of the credit assessment should be kept. A buyer who reorders within this period will not be subject to any further review.

operating mode

Choice between Test / Live. This determines whether the PAYONE platform is addressed in Test or Live mode.

Minimum value of goods

The minimum value of goods from which a credit check is carried out.

Maximum value of goods

The maximum value of goods up to which a credit check is carried out. The minimum and maximum goods value are checked against the Magento internal value "Subtotal", which does not include taxes (nor VAT) or shipping costs.

Invoicing Data

Click on PAYONE → Configuration → Misc

Invoice Information - Shipping Costs

Field Description

SKU

Here you can define the article number, how it should be transferred to PAYONE. If you do not require special treatment, leave the fields blank.

Invoice Information - Credit Memo

Field Description

Adjustment Refund SKU

Here you can define the article number for the correction reimbursement as it is to be transferred to PAYONE. If you do not require special treatment, leave the field blank.

Adjustment Refund Description

Here you can define the description for the correction reimbursement as it is to be transferred to PAYONE. If you do not require special treatment, leave the field blank.

Adjustment Fee SKU

Here you can define the article number for the correction surcharge as it is to be transferred to PAYONE. If you do not require special treatment, leave the field blank.

Adjustment Fee Description

Here you can define the description for the correction surcharge as it is to be transferred to PAYONE. If you do not require special treatment, leave the field blank.

E-mail configuration

Click on PAYONE → Configuration → Misc

Configuration e-mail in Case of Errors

Field Description

Enabled

Activates the mail reporting in case of error messages that arise in relation to the extension.

Sender

Here you can select who is the sender of the error mails. The contacts are taken from the Magento function of the addresses.

Recipient

Here you can select who is the recipient of the error mails. The contacts are taken from the Magento function of the addresses.

Copy to

Here you can select who is the additional recipient of the error mails. The contacts are taken from the Magento function of the addresses.

Template

Here you can select the template used to create the e-mail. However, you should always use the PAYONE e-mail error template.

E-mail Configuration AVS

The Address Verification System (AVS) is a American Express address verification system. The billing address entered by the end customer is compared with the billing address of the credit card.

Field Description

Enabled

Enables / disables the sending of mail, for AVS conditional information.

Send Mail for AVS-Value

Multiple drive selection of values that can be returned by the AVS system.

Sender

Here you can select who is the sender of AVS mails. The contacts are taken from the Magento function of the addresses.

Recipient

Here you can select who the recipient of AVS mails is. The contacts are taken from the Magento function of the addresses.

Copy to

Here you can select who is the additional recipient of AVS mails. The contacts are taken from the Magento function of the addresses.

Template

Here you can select the template used to create the e-mail. However, you should always use the PAYONE Email AVS template.

Export Configuration

Click on PAYONE → Configuration → Export Configuration

Clicking Export configuration will download a file.

You can now open this file with an XML editor and view or save it. This export is very important for every support request to the PAYONE team in order to avoid possible configuration problems. This file can also be used to determine whether any further extensions have been installed that could cause compatibility problems.

Transactionsstatus

Click on PAYONE → Transactions

Overview

Here you will find an overview of all transactions processed via PAYONE. By clicking on View, you can view details of the relevant transaction. You also have the option of filtering by payment type, status or amount, for example.

PAYONE Logs

Click on PAYONE → Logs

 

Under the menu item Logs you will find all information about processed payments and communication with the PAYONE platform.

Transactionsstatus Logs

Click on PAYONE → Logs → Transactionsstatus

Overview

The Transactions submenu item displays Magento received transaction status notifications for each order and transaction. These notifications are sent from the PAYONE platform to your shop. If there are any errors, you can find out here whether the transaction status was received correctly and what the current status is for a transaction. By clicking on View, you can display details on a transaction status.

Details

On the details page, you will see all the transaction status information transmitted through the PAYONE platform to your shop. Thus, you can always track which data your Magento shop has received and processed.

A detailed explanation of the respective parameters can be found in the technical documentation of the PAYONE platform in the PAYONE Merchant Interface (PMI) under Downloads → Documentation.

API Logs

Click on PAYONE → Logs → API

 

Overview

In this overview you will find all requests from the Magento shop to the PAYONE platform as well as the answers of the PAYONE platform to these requests. Only the requests that were transmitted to the PAYONE platform via Client API are not listed in this overview. This applies to credit card information that is transferred directly from the buyer's browser to the PAYONE platform using Ajax technology so that your shop does not come into contact with sensitive credit card information. By clicking on View, you can display an API request in detail.

Details

In the left column you can see the request that the Magento shop has sent to the PAYONE platform. On the right you will find the answer. A detailed explanation of the respective parameters can be found in the technical documentation of the PAYONE platform in the PAYONE Merchant Interface (PMI) under Downloads → Documentation.