Page tree
Skip to end of metadata
Go to start of metadata

General information

The current version of the PAYONE Payment Extension for WooCommerce enables the connection of WooCommerce to the BS PAYONE platform for the secure and automated handling of all payment processes.
The extension fits seamlessly into the existing checkout process of the WooCommerce shop.
In the WooCommerce administration area, extensive configuration and administration options are available. All functions of the extension can be configured individually and according to requirements.
The BS PAYONE Payment-Extension is constantly being further developed and is available to interested merchants for free download on Github.
Further information can be found at https://www.payone.com/woocommerce and http://www.payone.com.

Functional Description

Supported Payment Methods

The extension supports the processing of the following payment methods via the PAYONE platform.

VisaMastercardMaestroAmerican ExpressJCBDiners ClubDiscover

Information:
Depending on the respective acceptance contract, other payment methods such as Visa Electron, Visa Debit and other cards can also be processed via the aforementioned payment methods. Please contact us if you need further information.
Verified by VisaMasterCard SecureCodeAmerican Express SafeKey

GiropaySofort

SEPAPrepaymentInvoice

PayPalPaydirekt

PAYONE Secure Invoice

Installation

Wordpress Store

You can find our plugin in the Wordpress plugin directory. From there you can download and install the plugin as usual.

Github

Alternatively you can find the source files of the plugin in our Github Repository: https://github.com/PAYONE-GmbH/woocommerce-3 There you can check out the current version of the code e.g. via Git or download it directly as .zip.


Extract the archive with the BS PAYONE extension into the folder

/wp-content/plugins/payone-woocommerce-3

On your web server. Then you can activate the extension as usual in the plugin menu of Wordpress:


Permalinks in Wordpress
In order for the plugin to work properly, it is important that the Permalink settings in Wordpress are not set to "Simple".

Configuration in the PAYONE Merchant Interface

Transactionstatus URL

To enable WooCommerce to recognize the status of a payment, it is important that you enter the appropriate "TransactionStatus URL" in the PMI (PAYONE Merchant Interface). You will find the corresponding field under
Configuration > Payment Portals > IHR_PORTAL > Advanced > TransactionStatus URL The status URL follows the following scheme:

http(s):// >YOUR_SHOP< /payone-callback/

Please pay attention to the correct protocol that your system environment/hoster can process.

  • http
  • https


The fields Success-URL, Back-URL are automatically generated and passed by the WooCommerce extension in every request. These do not have to and should therefore not be filled.
The fields Purpose of use, Deactivate classic frontend do not have to be filled out or do not affect the proper operation of the extension.
The checkbox Deactivate Classic Frontend can also be ignored and Add Template is only used for the communication channel Frontend that is not contained in the extension.

It is important, however, that the field procedure hash value check which must not be set to sha2-384 exclusively, otherwise no communication from the shop to BS PAYONE is possible. All other options of the selection list can be used.

Configuration

General information

The global settings of the extension can be found after the installation in the backend under BS PAYONE. Here you carry out the basic configuration of the module.

The required data for the setup can be found clearly in the PMI

The parameters Merchant ID, Portal ID, Key and Subaccount ID are mandatory to operate the BS PAYONE Extension.

Do you not have access to the PMI yet? Request your test account here: https://www.bspayone.com/DE/de/channel/online

Global

Field

Description

Merchant ID

Your BS PAYONE dealer number.

Portal ID

The ID of the payment portal via which the shop sends its requests to the BS PAYONE platform.

Subaccount ID

The ID of the sub-account you created in the PMI (PAYONE Merchant Interface), through which the transactions are processed.

key

The key you assign in the PMI to encrypt requests to the PAYONE platform.

fashion

Mode of the transferred transactions. This can be "Test" or "Live". You can overwrite this setting later for each payment type.

  • Test - all transactions are carried out in test mode, the payment type is not debited. For tests, please use our document with test data, which you can download in the download area of the PMI.
  • Live - all transactions are passed on to the payment methods, if necessary the used payment method is charged.

Submit Cart

Specifies whether the article data in the shopping basket is to be transferred with the transaction. Some payment methods can then display and/or process this information as the order progresses. Some payment methods require the use of the feature. The feature is always used with these, even if it is globally switched off.

  • No - the BS PAYONE platform only receives the total basket value and no further information for transactions.
  • Yes - the BS PAYONE platform receives extended article data such as article number, description, quantity, unit price and tax rate.

Activate PDF Download

Indicates whether the SEPA Mandate can be downloaded as a PDF file for direct debit payments. Mandate PDFs created by BS PAYONE can be downloaded from the PMI at any time.

  • No - the mandate is not offered to the end customer for download.
  • Yes - The end customer receives a download link for the mandate on the order confirmation page after completion of the order.

Dynamic Invoice Text

Specifies whether and (if yes) which dynamic text should appear on an invoice generated by BS PAYONE.

The contents of the field are transferred in the parameter "invoiceappendix". The maximum length is 255 characters and different Woocommerce variables can be used as placeholders. You can use {{order} } to reference the current order number in WooCommerce in the request.

Dynamic Refund TextAlso here you can specify dynamic text that will appear on credits created by the BS PAYONE platform. (see above)
API log

Specifies whether the log for API calls from WooCommerce to BS PAYONE should be activated.

GDPR Note
The API logs may contain personal information. Please ask your legal advisor or data protection officer about data protection implications.

  • Deactivated - No log is kept over API calls
  • Activated - A log about the API calls is created.

Transaction Status Log

Specifies whether a log is to be kept of the transaction status messages received from the shop system.

  • Deactivated - No log of transaction status messages is kept.
  • Activated - Transaction status messages from BS PAYONE platform are logged

Payment Methods

You can access the settings for the individual payment methods via the WooCommerce menu (WooCommerce → Settings → Payments). Payment methods provided by the BS PAYONE plugin are marked with the prefix "Payone".

Recurring Configuration Options

All payment methods offer certain basic options.

Field

Description

Enable/Disable

Specifies whether the payment type is to be displayed in the checkout.

title

Specifies the name of the payment type in the checkout.

customer message

Here you can define an additional message to be displayed when you select the payment type.

Minimum Order Value

The payment type is only displayed from this shopping basket value onwards.

Maximum Order Value

The payment type is no longer displayed if the market-basket value exceeds this total.

Method of Authorization

Indicates whether the payment type is addressed by "authorization" or "preauthorization".

  • Authorization - Here the payment method is debited directly when ordering (where possible) and a claim is written on the BS PAYONE platform.
  • Preauthorization - As far as possible, payment will be reserved at the time of order. The payment has to be collected later in the order (see chapter "Orders").

Please note
Which authorization method is used for which payment method can have an effect on the cash flow. Which method you should use depends strongly on the business model and the payment type.

Active CountriesIn which countries should the selected payment method be active? By default, Germany, Austria and Switzerland are active. You can add or deselect further countries by "ctrl+click".
Use global settings

With this option, the global settings for the shop can be overwritten for specific payment methods.

  • Yes - the data active in the general settings will be used for this payment method.
  • No - After saving, the fields Merchant ID, Portal ID, Account ID, Key etc. appear again and can be filled with different data.

Credit card payment (Payone Creditcard)

Field

Description

Credit Card Brand

Here you can activate the credit card brands to be used for checkout. You can also define user-defined names for the individual markers.

Ask for CVC2

Defines whether the card security code is queried for credit card payments.

  • No - the CVC2 is not queried
  • Yes - the CVC2 is queried

From a purely technical point of view, querying the CVC is optional. However, most end customers are used to the query.

Minimum Validity of Card

Specifies the number of days a credit card used must still be valid for a transaction.

Credits on expired credit cards are not possible.

User-defined display for the hosted iframe

The WooCommerce Extension offers you as a merchant 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 of the

type

Selection of:

  • 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"

digit countLength of the field in characters ( HTML attribute size )
max digitsMaximum length of input ( HTML attribute maxlength )
iFrame

Selection of:

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

widthCSS - Specify width
HeightCSS - Indication of height
style
  • Default - Uses CSS specification from "Default Style"
  • Custom- Uses CSS specification from the following field
CSS

Specification of CSS properties for the field
Deactivated when Standard is selected beforehand.

All CSS properties except "url" are allowed. The following characters are prohibited: "\", "/", "?", "<" and ">"

default style
  • Text Input - CSS specification for all input fields (HTML input)
  • Select - CSS specification for all selection fields (HTML select )
iFrame
  • Width - CSS specification
  • Height - CSS specification
Error Output
Error Output ActiveSpecifies whether card payment errors are to be specified in the checkout.
Error Output Active (Language)Select the language in which the error message should be returned.

Ensuring Maximum Conversion With 3D Secure 2.0

Starting in mid-September 2019 Issuers demand more data during payment requests for more granular risk management and better fraud protection. While you can find more information here, you can make these configuration changes to ensure maximum conversion and frictionless credit card payments for your customers:

Make sure 3-D Secure is active in your Merchant Backend

Make sure you run the newest version of our plugin

Submit cart items for credit card orders

Request the following info during checkout (on by default)

  • phone number
  • shipping address
  • complete billing address

SEPA Direct Debit (Payone SEPA Direct Debit)

Field

Description

Check Bank Data

Specifies whether the IBAN is to be checked before the payment is made.

Use PAYONE Mandate Management

Specifies whether mandate management is to be used by BS PAYONE.

  • Yes - Within the framework of an order by SEPA direct debit, the customer is shown a mandate text as well as the mandatory data according to the SEPA Rulebook. The end customer must then confirm the mandate by ticking the box.
  • No - The BS PAYONE mandate management is not used.

Without a valid mandate, the customer can revoke the direct debit up to 13 months after payment via the bank!

Download mandates as PDF

If this function is activated, the SEPA Mandate is offered to the end customer for download after the order process (only if BS PAYONE Mandate Management is active).

List of supported bank countriesHere you can define from which countries SEPA direct debits should be possible.

Prepayment/Invoice (Payone Prepayment/Payone Invoice)

There are no specific configurations for these payment methods.

To avoid unexpected behavior when creating receivables and credit notes, please use the authorization method "Preauthorization" for prepayments.

clearing data
In the case of orders by prepayment or invoice the transfer must take place by the end customer. The necessary account data is dynamically generated and automatically written into the order confirmation or invoice mail from WooCommerce. Make sure not to remove this block when making adjustments.

Sofort./Giropay (Payone SOFORT.com/Payone Giropay)

There are no specific configurations for these payment methods.

PAYONE secured invoice (Payone Safe Invoice)

This payment method must use a different payment portal together with the corresponding portal key. In addition, the transfer of the shopping basket data is always active here. In order for the payment method to work as desired, it is therefore important that you enter the data from the "secured invoice" payment portal in your PMI in the fields provided for this purpose.

Field

Description

Portal ID

Portal ID of the dedicated payment portal for the PAYONE secured invoice from your PMI

key

The corresponding key

Note on the authorization method
With this payment method, careful selection of the authorization method is particularly important. Since with "Authorization" the demand is written immediately on the BS PAYONE platform, the platform also immediately sends a corresponding invoice. You should therefore use this authorization method above all if you perform the service immediately.

PayPal/Paydirekt (Payone PayPal/Payone Paydirekt)

There are no specific configurations for these payment methods.

Orders

The BS PAYONE WooCommerce Extension works in large parts automatically and integrates itself best possible into WooCommerce.

Overview

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

Workflow for Reservation and Capture

Orders placed using the authorization method "Preauthorization" are given the status "On Hold" after the order has been placed.

Only a status change to "Processing" activates the claim on the BS PAYONE platform and initiates (where possible) the collection of funds. Set the status to "Processing" and click on the blue "Update" button on the right.

The collection is then initiated on the BS PAYONE platform and acknowledged in the order notes:

Possible errors can also be found in the Order Notes.

Reserved payments are not reserved indefinitely. You should therefore take care to set orders to "Processing" in good time after a preauthorization and thus collect the payment or write the claim. Here are some (non-binding) guide values for the validity of the reservation:

Credit card - 7 days (sometimes longer, varies from bank to bank)

PayPal - 29 days

PAYONE Secure Purchase on Account - 28 Days

Workflow for Authorization

Orders that are created via "Authorization" automatically receive the status "Processing" if the BS PAYONE platform has successfully signaled the creation of the transaction to the shop. In this case, the claim is immediately written on the BS PAYONE platform and the money is collected (where possible) from the payment method.

Credit Notes

Credit notes use the familiar WooCommerce 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 WooCommerce. Use this option only if you do not want to transfer money back or if you use other ways than the BS PAYONE platform.

Please note with different tax rates and shopping basket transfer
Due to limitations in the way that WooCommerce manages orders, the shop's standard tax rate for the entire credit amount is always transferred for credit notes with shopping basket transfer. This is especially important when the BS PAYONE platform takes care of document dispatch for you. This is the case, for example, with the PAYONE Safe Invoice payment method.

As long as the credit memo only contains articles that are subject to the shop's standard tax rate, you can use the credit memo function without hesitation. However, if you wish to credit a shopping cart that contains items with different tax rates or mixed tax rates, please use the credit function in the PAYONE Merchant Interface. There you have the option of creating individual shopping basket items together with the tax rate, which are then displayed correctly on the document.

Error handling and chargebacks

Some payment methods allow the end customer to withdraw the money after payment. In this case the BS PAYONE platform informs the shop about the transaction status. The status of the affected order changes to "Failed" and the extension also shows the chargeback in the order notes. Where available, we shall state the reason for the chargeback.

An overview of the reasons for chargebacks can be found in chapter 5.1 of the Server API documentation.

Logs

API log

Under "API-Log" you will find the detailed API calls that WooCommerce sends to the BS PAYONE platform. Here you will also find detailed technical information on the response to the BS PAYONE API, which you can use for debugging purposes.

Transaction Status Log

The Transaction Status Log displays all feedback on payments made that the shop receives from the BS PAYONE API. This information can also be helpful during debugging.

Information and Support

Do you have any bugs or suggestions to improve the code of the extension? Open an issue in our Github repo story: https://github.com/payone-gmbh
If you have any questions regarding the installation or use of the BS PAYONE Extension, please contact our Technical Support at the following contact details:

technical support

for technical questions

email

tech.support@bspayone.com

Phone

+49 431 259 68-500

Merchant Service

for billing and contract issues

email

merchantservice@bspayone.com

Phone

+49 431 259 68-200

Quick Facts

Download

Transactionstatus URL:

<SHOPURL>/payone-callback/

LATEST RELEASE     v1.5.0
 Click here for release details

New Features
  • more compatibility when querying order numbers
  • New translations for German (informal) and Swiss
  • Submit Customer IP and Shipping Data with every payment method

Bugfixes

  • Discounts are now calculated correctly

Maintenance

  • tested with Woocommerce 3.7
  • tested with Wordpress 5.2

  • No labels