Integration Guide Oxid 7

Introduction

Our Oxid 7 plugin comes with regular updates and full integration support, offering a versatile out-of-the-box solution to accept online payments easily:

Currently supported payment methods:

  • Credit Cards (Visa, Mastercard, American Express, JCB, Diners Club, Maestro International, Carde Bleue)
  • Alipay
  • Apple Pay
  • Bancontact
  • Barzahlen
  • EPS
  • Giropay
  • iDEAL
  • Klarna Payments
  • PAYONE secure Invoice
  • PAYONE Secured Invoice, Secured Direct Debit and Secured Installment
  • PAYONE Direct Debit
  • PAYONE open Invoice
  • PAYONE Prepayment
  • PayPal and PayPal Express
  • PostFinance Card and E-Finance
  • Przelewy24
  • Sofort
  • Ratepay Invoice, Direct Debit and Installment
  • Trustly
  • Unzer Invoice, Direct Debit and Installment
  • 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: v1.0.0

Download Plugin

Requirements

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

Plugin Installation

You have 2 ways to install our plugin:

Installation via Composer

Oxid 7 uses composer for dependency management, so our extension is also installed via composer. Please perform the following steps to install the extension:

SSH to the directory of your Oxid composer.json file and perform the following command:

Befehl
composer require payone-gmbh/oxid-7

Installation via Github

Download from 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?cl=FcPoTransactionStatusHandler

Additional Response-data

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

Oxid 7 - Admin configuration

Activate the module in the Oxid backend.

    Payment methods setup

    In the menu item Configuration → Payment methods both the standard payment methods of your OXID eShop and the payment methods available via PAYONE are displayed. Here you can configure the desired payment methods.

    The PAYONE payment types are an extension of the OXID standard payment types and offer additional options. To display only the PAYONE payment types, use the filter function PAYONE Only in the header of the payment type table.
     

    Overview

    The overview shows you all PAYONE payment methods that are available for configuration. Please only configure the payment methods that have been activated for your merchant account.

     

    Basic Configuration

    You can recognize all PAYONE payment methods by the displayed logo.

    Field Description

    Authorization-Method
    • Preauthorization - 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.
    • Authorize - The amount tobe paid is collected immediately when the order is placed. The receivable is immediately booked on the PAYONE platform.

    PAYONE Operating 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.

    Active

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

    Name

    Name of the payment method, which will be displayed in the checkout.

    Price Surcharge/ Reduction

    Here you can set a price premium/discount for the payment type. The prices can be indicated in two different ways:

    • abs - indicates the absolute price (e.g. if you enter 7.50, 7.50 euros will be charged).
    • % - calculates the price in relation to the shopping cart value. (Example: enter "2", 2% of the cart value will be added). You can also enter negative values. (Example: enter "-2", 2% of the cart value will be deducted).

    min. Credit Rating

    Here you can specify that certain payment types are only available to users/buyers who have at least the defined creditworthiness index. You can enter the credit rating index for each user under the menu item Manage User → User → Advanced.

    If you have ordered the Protect module from PAYONE, you can automatically deposit this value with the respective user / buyer using the credit check. 

    Settings for payment types without the PAYONE indicator have no effect on processing via PAYONE.

    Payment Settings

    The global configuration settings for communication with the PAYONE platform are made under PAYONE → Configuration → PAYONE Payment Settings.

     

    Connection Settings

    Field Description

    PAYONE Merchant ID

    You will find your PAYONE Merchant ID at the top right of the PAYONE Merchant Interface (PMI) and on all PAYONE invoices.

    PAYONE Portal ID

    Please enter the ID of the PAYONE payment portal you want to use to process the payments. The Portal ID can be found in the PAYONE Merchant Interface (PMI) under the menu item Configuration > Payment Portals.

    PAYONE Portal Key

    The configuration can be found in the PAYONE Merchant Interface (PMI) under the menu item Configuration → Payment Portals → [Edit] → Tab [Advanced] → Key

    PAYONE Sub-Account ID

    Please enter the ID of the sub-account you want to use to process the payments. The ID can be found in the PAYONE Merchant Interface (PMI) under the menu item Configuration → Accounts

    Reference number Prefix

    Here you can configure how the reference number is supplemented to ensure uniqueness for the transfer to PAYONE.

    This setting is required, for example, if you are running the extension on a test system and a production system.

    Hash Method

    This setting corresponds to the hash setting in your payment portal.

    The PMI and shop settings have to match for credit card payments to work correctly. We strongly recommend setting both to sha2!
    General information

    Field Description

    Send article list

    Here you can configure that the article information is also transferred to PAYONE.

    This option only needs to be activated if you have booked the Invoicing module with PAYONE.

    Save order before authorization

    Here you can define whether the order is already saved before the payment confirmation. These orders are then in a wait status.
    Special adjustments
    Credit Card

    The Creditcard payment method in the extension is divided into various subtypes (card brands).

    You can activate or deactivate the respective card type in the overview. You also have the option of assigning countries from which you wish to accept the card to the respective card brand. In addition, you can set for each credit card brand whether it is activated in live or test mode.

    Local card brands should only be assigned for the respective country (e.g. JCB = Japan). In addition, the respective card brand must have been ordered and activated for your merchant account.
    Credit Card Configuration

    The Oxid Extension 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 to customize these fields.

     

    Field Description

    Request-type

    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".
    • Password - input type="password"
    • Text - input type="text"
    • Selection - drop-down list

    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 

    The use of the attribute "url" leads to a non-display of the field

    Standard-style

    Input-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

    Active

    Enables error output in checkout related to credit card entries.

    Language

    Selection of the display language for the error messages.

    PAYONE Direct Debit

    In the direct debit area, you can make settings with regard to the SEPA procedure (Single European Payments Area).

     

    Field Description

    countries

    Selection of countries for which direct debit may be offered.

    Account number Display bank sort code

    For German accounts, it is still possible to display the account number and bank sort code in addition to the IBAN / BIC. With this selection you activate the display.

    Active mandate allocation

    Activates the mandate management of PAYONE.

    Download mandate as PDF

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

    PayPal

    Field Description

    In case of missing delivery address, the billing address will be handed over as delivery address.

    If no explicit delivery address or a different delivery address has been specified, the billing address will be transmitted as the delivery address for the payment method PayPal - if the checkbox is activated.

    active

    Activates the entry

    language

    Language to which this entry applies. Only languages created in the OXID eShop are displayed.

    logo

    Preview of the uploaded logo, which will be used later in the checkout.

    upload

    At this point the logo can be selected. 

    standard

    If activated, the entry or logo of this entry will be the default for all languages where no logo is available.
    Unzer Payments

    Field Description

    Operate Payolution in B2B mode

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

    Company's name

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

    Payolution Username

    In order to retrieve the installment purchase draft contract, the user name assigned by Paysafe must be stored here.

    Payolution Password

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

    Ratepay

    For Ratepay Invoice to work, please add your profile ID and provide the corresponding currency.
    When B2B mode is activated and the company name specified by the user, the VAT ID no. is requested. For B2C customers the date of birth is requested instead.

     
    PAYONE Secured Invoice + PAYONE Secured Installment

    These two payment methods require their own payment portal. Please enter under Customers → Payments → PAYONE → Konfiguration → applies to payment method: PAYONE Secured Invoice bzw. PAYONE Secured Installment a separate portal ID.

    If the orders are partially captured, the refunds must be created in the same amount. The background is that a new receivable is created with each capture.

    Giropay

    Field Description

    Secured pre-order

    In the case of a secured pre-order, the retailer is granted a payment guarantee for the selected period (maximum 15 calendar days). Captures (partial payments) must always be executed within the guarantee period.
    Editing the orders

    Orders placed via the PAYONE Extension for Oxid are listed as usual in the order overview of Oxid. Order processing differs depending on the authorization method used to process the order.

    Capture

    Orders placed using the "Preauthorization" authorization method must be captured. In the order details you will find an additional tab "PAYONE". Here you can capture the order.

    The collection is then initiated on the PAYONE platform.

    Refund

    Credit notes use the familiar Oxid credit note process. A click on the button "Refund" in the order opens the menu for credit notes.Here you can enter the amount credited and a reason. Important: "Refund manually" does not credit the money on the payment method, but only in Oxid. Use this option only if you do not want to transfer money back or if you use other ways than the PAYONE platform.

    Extended configurations

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

    Protect

    Under the menu item PAYONE → Protect you can configure credit and address checks as well as bank account checks.

    Here you can specify for the credit standing check whether the checks are carried out in test or live mode.

    The Protect module must be enabled for your merchant account to use these options. Incorrect configuration leads to unwanted interruptions in the checkout process.
    Credit Assessment

    Here you can specify whether and in what form creditworthiness checks are to be carried out during the checkout process.

    Field Description

    Consumerscore check
    • Do no perform consumer score check - no request is made to the PAYONE platform.
    • Infoscore (Hard features) - Checking for hard characteristics via infoscore (e.g. consumer insolvency proceedings, arrest warrant for affidavit or enforcement of affidavit)
    • Infoscore (All features) - Examination for so-called "hard" negative features (see above) and "medium" negative features (e.g. order for payment order, enforcement order or enforcement) and "soft" negative features (e.g. collection dunning procedure initiated, continuation of out-of-court collection dunning procedure after partial payment, discontinuation of out-of-court collection dunning procedure due to hopelessness)
    • Infoscore (All features + Boniscore) - Checking for all characteristics (see above) and delivery of the BoniScore, which as a score value enables a higher selectivity for existing negative characteristics.
    • Boniverse VERITA Score - Check for VERITA-Scores via Boniversum

    Moment of consumerscore
    • Before paymenttype selection
    • After paymenttype selection - you can select the creditworthiness index for the payment type so that a check is only carried out for certain payment types.

    Lifetime credit check in days

    Number of days for which the credit standing value returned is valid. No new credit checks will be carried out for the set period for the relevant shop buyer / user until the set period expires. If this field is empty, a request is always made.

    Credit check up from minimum value of goods (€)

    Market-basket value from which a credit check is carried out. If this field is empty, a request is always made.

    Standard credit index

    The customer receives this credit rating index when he registers.

    Purpose: If the customer has not yet been checked and the check only takes place above a certain goods value, this is the credit rating index which is taken into account until the first actual check. If this field remains empty, the OXID standard is set (1000).
    Please make the settings for the credit check with caution. Incorrect configurations can result in errors in the checkout process and unwanted costs due to an increased number of queries and an unnecessarily high risk of payment defaults. You should only use the credit standing check for payment types that entail a payment default risk for you (such as open invoices or direct debits). You configure this via the setting "Credit rating index" in the configuration of the respective payment type. You should also indicate in your shop in an appropriate manner that you are conducting credit checks via infoscore Consumer Data GmbH.
    Address Validation

    Here you can specify whether and in what form the address checks should be performed and how the OXID eShop should behave if certain results apply.

     

    Field Description

    Addresscheck
    • Do not perform addresscheck - No address check is performed.
    • AddressCheck Basic - Address check for existence (street number, postcode, city, country) as well as addition and correction of address (possible for addresses from Germany, Austria, Switzerland, the Netherlands, Belgium, Luxembourg, France, Italy, Spain, Portugal, Denmark, Sweden, Finland, Norway, Poland, Slovakia, Czech Republic, Hungary, USA, Canada).
    • AddressCheck Person - Checking whether the person is known at the address given, checking the existence of the address and supplementing and correcting the address (Germany only).
    • Boniversum Addresscheck Basic
    • Boniversum Addresscheck Person

    Commit corrected addresses

    An address corrected by the PAYONE platform is adopted

    Check delivery address

    A different delivery address will also be checked on the basis of the selected address check.

    If the option "Apply corrected address" is selected, corrected delivery addresses will also be applied.

    If postal address is incorrect, users will be sent back to the user form

    If the described condition applies, the user is asked again to enter his invoice/delivery data in the checkout.
    Bank details check

    Here you can configure whether and in what form bank details should be checked during the checkout process when the payment type Direct Debit is selected.

     

    Field Description

    Check bank account
    • Inactive - No check of the bank details
    • Active - The system checks the plausibility of the account details.
    No check is made for the existence of the bank details or account coverage.
    • Active, with check against POS CRL - A check of the bank details for plausibility and a check against the POS block list is performed.
    Here, too, no check is made for the existence of the bank details or coverage of the account. The POS block file contains account connections with open chargebacks from stationary trading.

    Transaction Status redirects

    Field Description

    Logs

    With this option activated, you can log activity of transactionstatus redirects. Content of this logging are landing in file fcpo_message_forwarding.log in your shops log folder.

    Redirect-Method
    • Direct redirect - Using this method will directly redirect the transaction after receiving it. This mode offers a high redirection speed and a moderate transaction security.
    • Delayed by Cronjob - Instead of directly redirecting the statusmessage, this method collects incoming messages and will redirect them aftery calling a cronjob. This mode offers a very high transaction security. The speed of redirecting statusmessages depends on the setup of your server.

    Timeout

    For offering direct redirects without any interruptions, there is a need for having a timout for mode "Direct redirects".

    Transaction Status Forwarding

    Transaction status forwarding enables you to transfer the payment status to other systems, such as Materials Management or Logistics.

    Field Description

    Status

    The status sent by PAYONE.

    URL

    Enter the receive URL to which the status is to be forwarded.

    Timeout

    Number of seconds to wait until the status is accepted.
    Delete Here you can delete the respective forwarding.

    Save

    Saving saves all redirects in the database.

    Add

    You can add as many redirects as you like. Also multiple forwarding for one and the same status.

    Transaction Status Mapping

    The transaction status mapping is used to use the PAYONE status in order to have the orders processed according to your needs in an appropriate shop status.

     

    Field Description

    payment-method

    The payment type for which the mapping is to apply.

    PAYONE Status

    The status sent from PAYONE to the shop.

    Shop - Status

    The status that the orders should assume when the configured PAYONE request is processed in the shop.

    delete

    Here you can delete the respective mapping.

    Save

    Saving saves all mappings in the database.

    add

    You can add any number of mappings. Please note, however, that only one mapping exists for a payment type and PAYONE status combination. This may lead to inconsistencies.

    Logs

    Within the menu item Protocols/Logs you will find all information about processed payments, the communication with the PAYONE platform as well as the order overview.

     

    Transactions

    The Transactions submenu item displays notifications received from the OXID eShop of the transaction status of the PAYONE platform for each order and transaction. 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.

    In the overview you can see all received and processed messages of the transaction status of the PAYONE platform. Filter options are available above the individual columns.

     

    Field Description

    time

    Time at which the transaction status was received.

    order number

    The order number of the order in the OXID eShop.

    transaction number

    The unique number of the transaction (TXID). This number is assigned by the PAYONE platform.

    payment method

    The payment type used within this transaction is displayed here.

    The following abbreviations are possible:

    elv - Direct debit
    cc - credit card
    rec - invoice
    cod - cash on delivery
    sb - online bank transfer
    wlt - e-Wallet (e.g. PayPal)
    fnc - Financing (e.g. Klarna)

    customer email

    The e-mail address of the customer that was specified in the order.

    amount

    The amount in the currency used.

    status

    This displays the status transmitted by the transaction status of the PAYONE platform.

    An explanation of the individual statuses can be found in the technical documentation of the PAYONE platform in the PAYONE Merchant Interface (PMI) under Downloads → Documentation.

    Transaction details

    After selecting an entry in the overview, you will receive all transmitted transaction status information through the PAYONE platform to your OXID eShop. This allows you to track at any time which data your OXID eShop 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

    In the submenu API-Logs you will find all requests from the OXID eShop to the PAYONE platform as well as the corresponding answer of the PAYONE platform.

    The only requests that are not contained in these logs are requests using the Client API. The reason for this is that these requests are sent directly from the buyer's browser (client) to the PAYONE platform for reasons of the Payment Card Industry Data Security Standard based on Ajax technology, so that your OXID eShop does not technically come into contact with sensitive credit card data.

    In the overview you will find a list of all requests from the OXID eShop to the Server API with basic information. You can filter the display in the column headers by entering search terms.

     

    The entire content of the Request and Response columns is searched. The content is described in more detail in the API Log Details.

    Field Description

    time

    Time of the request.

    channel

    The channel used.

    Request

    Type of request.

    Response

    		 Parameter "status" from the response of the PAYONE platform to the request.
    API Log Details

    After clicking on one of the requests listed in the overview, you will see all parameters of the request sent to the PAYONE platform as well as the corresponding response from the PAYONE platform.

    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.
    Orders

    The order overview is a standard functionality of the OXID eShop. The PAYONE tab has been added to this list in order to be able to check the payment status of an order.

    Via the menu item Manage orders → Orders, which is available by default in every OXID eShop, the same overview including the PAYONE tab is displayed as under PAYONE → Protocols / Logs → Orders.

     

    Field Description

    order time

    Time of order

    Paid

    Time for reporting the payment from the PAYONE platform.

    Order no.

    Order number of the OXID eShop.

    client

    Name, first name of the customer.

    PAYONE reference number

    The reference number passed to the PAYONE platform for unique identification. The reference number is stored in the "reference" parameter.
    PAYONE Tab

    In the PAYONE tab you will find the transaction account in the context of the order, in which all receivables and payments are displayed. This is based on the OXID eShop requests via the Server API to the PAYONE platform as well as feedback on the transaction status from the PAYONE platform.

    You also have the option of capturing payments for pre-authorized payment transactions and refunds.

     

    Field Description

    reference number

    The reference number passed to the PAYONE platform for unique identification. The reference number is stored in the "reference" parameter.

    PAYONE Process number (TXID)

    The transaction number under which the transaction was processed in the PAYONE platform.

    method of payment

    Payment type with which the order was executed.

    payment details

    Depending on the payment method, detailed information about the payment is listed here. For credit card payments, the fields Card type and Masked card number are displayed here as information.

    amount

    Depending on the payment status of the order, you can trigger a credit note (refund) or carry out a payment collection (capture) at this point.

    In the accounts receivable management in the PAYONE Merchant Interface (PMI) there are more far-reaching possibilities for the execution of captures, refunds etc. available. In addition, you can trigger these transaction types via your merchandise management system or/and? via the server API of the PAYONE platform.

    transaction account

    All receivables and payments for the purchase order are displayed here in the form of a transaction account. All negative amounts are displayed in red. Click on "Time" to open the corresponding transaction status.