OXID 6 Integration Guide

Version: v1.13.1

📋 Navigation: Click on the tabs below to explore different sections

Introduction

Our OXID 6 plugin is regularly updated and provides a versatile, ready-to-use solution for easy online payment acceptance.

Supported Payment Methods

💳 Credit Cards

Visa (Click to Pay), Mastercard (Click to Pay), American Express
JCB, Diners Club

📱 Wallets

Apple Pay
Google Pay
PayPal and PayPal Express
PayPal v2 and PayPal Express v2
Alipay
WeChat Pay
WERO

🏦 PAYONE Solutions

PAYONE Secure Invoice
PAYONE Secured Invoice, Secured Direct Debit and Secured Installments
PAYONE Direct Debit
PAYONE Open Invoice
PAYONE Prepayment

🌍 Additional Payment Methods

Klarna Payments
Ratepay Invoice, Direct Debit and Installments
Unzer Invoice, Direct Debit and Installments
Bancontact, EPS, iDEAL
PostFinance Card and E-Finance
Przelewy24

Requirements

An active PAYONE account is required. If you don't have one yet, please contact us.

Admin Configuration

Activate the module in the OXID backend.

Payment Methods Configuration

Under 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 ▼

Field	Description
Authorization Method	Pre-authorization - The amount to be paid is reserved. In this case, the debit must be captured in a second step during shipping. Authorization - The amount to be paid is immediately debited when the order is placed. The claim is immediately posted 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/Discount	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.
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.

Payment 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!

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 Customizations

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. Carte Bleue = France). 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 strongly 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 ▼

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
Use Billing Address as Shipping 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 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 Name	The full name of the company must appear here. The name will be used in the privacy policy.
Unzer Username	In order to retrieve the installment purchase draft contract, the user name assigned by Unzer must be stored here.
Unzer Password	The password assigned by Unzer must be stored here in order to retrieve the installment purchase draft contract.

Ratepay ▼

PAYONE Secured Invoice + PAYONE Secured Installment ▼

Advanced 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
Consumer Score Check	Do not 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 Consumer Score	Before payment type selection After payment type 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 from Minimum Value (€)	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
Address Check	Do not perform address check - 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	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.

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 transaction status 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 status message, this method collects incoming messages and will redirect them after calling a cronjob. This mode offers a very high transaction security. The speed of redirecting status messages depends on the setup of your server.
Timeout	For offering direct redirects without any interruptions, there is a need for having a timeout for mode "Direct redirects".

Transaction Status Forwarding ▼

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 ▼

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.