Barion x WooCommerce - Documentation

¶Introduction

Barion x WooCommerce is a WordPress plugin that enables the integration of the Barion payment service into WooCommerce online stores. With this plugin, store owners can easily and securely accept online payments through the Barion system.

¶Obtaining a License and Configuration

You must obtain the license and complete the configuration before installation.

• Register in the Shop
• Click the confirmation link in the email you receive
• Log in to the Shop
• Create a billing profile in the Shop
• Purchase the product in the Shop
• Pay by credit card or bank transfer
• Select the license in the Shop
• Activate the license by entering the WordPress Address (URL, not the Site Address) in the Shop
• Download the plugin from the Shop
• Upload and activate the plugin in WordPress
• Copy the license key from the Shop
• Configure the license key in WordPress

¶Purchasing a License

The plugin is sold under a license. You can purchase it via the Cone Shop: https://shop.conedevelopment.com/barion-x-woocommerce. After registering, logging in, and providing your billing details, you can purchase licenses for as many sites as you need.

After the purchase, the system automatically generates a license key. First, you must activate your store URL for this key, and then, after installing the plugin, you must enter the license key in WordPress.

¶Activating the URL / Domain

You can access previously purchased licenses at https://shop.conedevelopment.com/account/licenses.

Within each license, you can associate your store’s URL with the license key, ensuring that later activation will succeed.

¶Installation

You can perform the installation after obtaining the license and completing the configuration.

¶Via the WordPress Plugin Manager

On the license settings page, select the desired version and download the plugin, which you can then install on your WordPress instance.

After downloading, locate the .zip file and upload it to the target WordPress instance.

1. Navigate to Plugins → Add New.
2. Click the Upload Plugin button at the top.
3. In the new section that appears, click to choose a file, then select the .zip file you downloaded earlier.
4. Click the Install Now button.

After the upload, you will see a screen confirming that the plugin has been successfully installed. This is a simple page where you can follow the steps of the installation process.

As you can see on this screen, you can activate the plugin immediately. Click the Activate Plugin button and your Traffic Cop plugin will start running.

If you skip activation on this page, you can always activate (enable/disable), delete, or update the plugin later under Plugins / Installed Plugins.

You can find the plugin settings under Plugins / Installed Plugins / Barion x WooCommerce by clicking the Settings link.

Here you can assign the license key to the plugin. This is an important step, because without validation the plugin will not work, and updates cannot be downloaded via the WordPress system.

¶Via the Composer Package Manager

Composer is a widely used dependency manager for PHP applications. In some setups, you may want to manage your WordPress installation and its dependencies with Composer.

The example composer.json below shows how to configure the conedevelopment/barion-woocommerce package so that Composer can download it from the correct location.

{
    "name": "conedevelopment/example-wp-composer",
    "description": "Example WordPress with Composer",
    "license": "MIT",
    "require": {
        "php": "^8.3.0",
        "conedevelopment/barion-woocommerce": "^1.4.2",
        "roots/wordpress": "^6.6.0"
    },
    "minimum-stability": "beta",
    "config": {
        "preferred-install": {
            "*": "dist"
        },
        "allow-plugins": {
            "composer/installers": true,
            "ffraenz/private-composer-installer": true,
            "roots/wordpress-core-installer": true
        }
    },
    "extra": {
        "installer-paths": {
            "wp-content/mu-plugins/{$name}/": [
                "type:wordpress-muplugin"
            ],
            "wp-content/plugins/{$name}/": [
                "type:wordpress-plugin"
            ],
            "wp-content/themes/{$name}/": [
                "type:wordpress-theme"
            ]
        }
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://wpackagist.org"
        },
        {
            "type": "package",
            "package": {
                "name": "conedevelopment/barion-woocommerce",
                "version": "1.4.2",
                "type": "wordpress-plugin",
                "dist": {
                    "type": "zip",
                    "url": "https://shop.conedevelopment.com/api/packages/{%CONE_LICENSE_KEY}/download?version=v{%VERSION}"
                },
                "require": {
                    "composer/installers": "^2.3.0",
                    "ffraenz/private-composer-installer": "^5.0"
                }
            }
        }
    ]
}

The {%VERSION} placeholder resolves to the value of the version key, 1.4.2 in this case. However, it is not recommended to store {%CONE_LICENSE_KEY} directly in composer.json (especially if this file is tracked in Git). Instead, you should place it in an environment variable. This can be a .env variable or an environment variable defined in your CI (GitHub Actions, GitLab CI, etc.):

# Not a real license key!

CONE_LICENSE_KEY=eb819bed-ba18-4e60-9d95-d6d6b5d4364c

¶System Requirements

The plugin covers a fairly wide range of compatibility, which is advisable for a WordPress plugin. Regardless, it is important that your WP version and server are as up-to-date as possible, both for security and performance reasons.

• PHP: 7.4+
• WordPress: 6.0+
• WooCommerce: 8.0+

¶Settings

The plugin offers the following configuration options:

• License Key: Here you need to enter the plugin license key, which you can obtain from the Cone Shop - Licenses page.
• POSKey: The API key associated with the point of sale, which can be obtained from the Barion interface.
• Barion Email: The email address associated with the Barion account where payments are received.
• Barion Pixel ID: An optional field containing the Barion Pixel ID for conversion tracking. This setting is required for both basic and full pixel usage.
• Test Mode: Check this box if you want to use the plugin in a test environment.
• Reservation (Two-Step) Payments: Check this box if you want to accept reservation (two-step) payments.
• Apple Pay Settings: Settings required to use integrated Apple Pay.
• Google Pay Settings: Settings required to use integrated Google Pay.
• Debug Settings: Here you can find settings related to debugging.

¶Barion Order Identifier (OrderRef)

By default, the plugin does not pass a prefixed order identifier (e.g., wc-889) to Barion, but rather the order key (e.g., wc_order_q6MXBjFKQwm7B), which is completely unique.

This is necessary to prevent conflicts in the system caused by plugins that can override the order identifier (e.g., WooCommerce Sequential Order Numbers Pro).

If you want to modify the identifier, you can do so using the barion-woocommerce_order_ref filter:

add_filter('barion-woocommerce_order_ref', function (string $ref, WC_Order $order): string {
    return 'xyz-'.$order->get_order_number();
}, 10, 2);

¶Barion Pixel

Barion Pixel is a statistics service (Barion Metrics), similar to Google Analytics or Facebook Pixel.

The key difference is that this is Barion's own service, which they shape and control as they wish. Its great advantage is that user statistics are used not only for marketing but also for security.

The code works similarly to GTag, tracking the user with events and collecting data about them. This data is not general but optimized for e-commerce, i.e., online sales. There are two types of Barion Pixel: basic and full. The basic one comes with the payment gateway, while implementing the Full version requires additional effort.

While fraud protection is included in both, advanced statistics and lower fees are only available with the Full Barion Pixel.

¶Cookie Management

As with any case where we use an external service on our site for data collection, we also need to update the related data and cookie management for Barion Pixel to properly inform users.

¶General Expectations

In Hungary (within the EU), the applicable directive is the GDPR. Generally, by following the GDPR, we are almost certainly compliant with other similar regulations (such as the CCPA), but we should always act according to the laws of the specific region based on our target audience.

In the case of Barion Pixel (as with any other third-party service), compliance with these regulations is the sole responsibility of the site operator.

• You must inform the user about the existence and nature of data collection.
• Data collection can only occur if the user consents to it. This is where cookie consent modules come into play, where the user explicitly agrees.
• After giving consent, the user must be able to withdraw their previous decision.

How you achieve all this is up to you. In WordPress, there are many plugins that can help with this, but you can also create a custom solution. Generally, cookie management requires a more complex solution, partly due to the conditions mentioned above.

It is important to properly initialize the tracking code, meaning the cookie banner should not just be an information notice but should actually function.

¶Recommended Cookie Consent Text

The role of the cookie consent banner is to provide a brief and concise notification, with all other necessary details available on related pages such as "data" and "cookie management." If you do not yet have such a page on your site, a similar text can be a good starting point:

We use cookies and similar technologies on the site to track users. Some cookies are essential for the site to function. While others, such as statistics or marketing, are optional. By clicking "Accept", you consent to their use, while the "More settings" button allows you to customize them as desired. More details can be found under the cookie and data management pages.

The bold parts should be linked to the appropriate pages. Naturally, this is a sample, a guideline, so customize it as you wish.

¶Cookie Policy

You must list the following basic (i.e., always necessary) cookies on your related cookie policy page.

The lifespan of cookies depends on the last update. After the user has consented, no re-consent is required until the expiration of the duration.

For personalized marketing and advertising, the following cookies must be listed.

Marketing cookies are optional. If there is no consent for them, Barion does not use and track the related functions. Barion Payment Zrt. collects data about site visits, what the user clicks on, or what products or services they are interested in. It also tracks if a purchase process gets stuck. It broadly collects data about the user and their behavior to offer personalized content and advertising.

The goal is to be able to target those customers who are truly interested in a given product; this can only be accomplished precisely with the related cookies enabled.

Barion Payment Zrt. shares this data with its data processing and advertising partners. You can find more information in Barion's privacy policy.

[*] This description is based on Barion's official documentation. Before publishing anything on your site, make sure our translations are correct compared to the original content.

¶Basic Pixel

To use the Basic Pixel, no additional settings are required; you only need to enter the Barion Pixel ID in the plugin settings. After that, the plugin automatically inserts the necessary code into the webshop and applies the basic functions.

¶Full Pixel

As a prerequisite for more favorable merchant packages, it is also possible to insert additional extended code, which aims not only at fraud prevention but also at data collection for marketing purposes. This is the full or complete pixel.

The Barion Pixel placed on the website collects data about visitors, such as what products they viewed, what they clicked on, searched for, added to cart, and purchased.

Since data collection is the goal here, explicit consent is required from the customer. Barion also checks this before approval!

The plugin provides an opportunity to easily connect the Pixel approval/rejection events to a custom-developed or plugin-integrated consent manager solution.

We can activate or deactivate this with a JavaScript event:

// Acceptance
document.dispatchEvent(new CustomEvent('barion:consent', { detail: { accepted: true } }));

// Revocation/denial
document.dispatchEvent(new CustomEvent('barion:consent', { detail: { accepted: false } }));

Data is transmitted to Barion's servers; it is not collected, stored, or processed by the Merchant.

¶CookieYes integration example

CookieYes is one of the most popular cookie management plugins. The first step is to categorize the cookies defined by Barion (which can be divided into two groups) into the appropriate categories. The basic cookies belong to the functional group, as they are necessary for the operation of the basic Pixel. The second group pertains to the Full Pixel functionality, which involves optional cookies. In this case, we categorized them under the analytics group, but different settings can be applied.

To facilitate simple integration, the following sample code can be used or modified as needed:

<script>
    document.addEventListener('cookieyes_consent_update', function (e) {
        document.dispatchEvent(
            new CustomEvent('barion:consent', { detail: { accepted: e.detail.accepted.includes('analytics') } })
        );
    });
</script>

It is recommended to place the code in the <head> element or just before the </body> tag.

¶Setting up reservation/two-step payment

It is possible to use reservation (two-step) payment solutions through Barion, which our plugin also supports.

¶What exactly does reservation payment mean?

In a one-step payment, after providing the card details, Barion immediately charges the amount from the card. In most cases, this procedure is perfectly sufficient.

However, there may be cases when the final amount of the order is only known later, after the order is placed and paid. In this case, it is possible to initiate reservation transactions, which after providing the card details, do not charge but only reserve (pre-authorize) the given amount, and then in a second step, when the merchant knows the exact amount of the order, they can charge the reserved amount via an API request (sent manually from the WooCommerce orders page).

In the second step, it is not possible to charge more than the originally reserved amount. Therefore, after modifying the order value, the maximum chargeable amount can only be the reserved amount.

¶Enabling reservation payment

You can enable reservation payment in the plugin settings (WooCommerce / Settings / Payment Methods / Barion):

Note: enabling this will make all Barion transactions reservation-based.

¶I want to enable or disable reservation payment only for certain orders. How can I do this?

It may happen that we only want to enable this feature in certain cases, so we can handle this with the barion-woocommerce_reservable filter tied to a custom condition (when we want reservation payment).

¶Charging or releasing the reserved amount

The second step, i.e., charging or releasing the reserved amount, can only be initiated manually on the order admin interface.

If the recalculated order amount is greater than the originally reserved amount, to avoid an error in the API request, the reserved amount will be passed.

Under the "Order actions" box, there is a new option that, when executed, initiates the API request to Barion. After this, Barion sends an IPN to the webshop, which the plugin processes similarly to one-step payment.

¶Recurring payments

The most popular - and perhaps the best - solution for managing recurring payments and subscriptions is the WooCommerce Subscriptions plugin.

Our plugin only provides integration with WooCommerce Subscriptions.

¶Supported subscription actions and known limitations

* This limitation refers to using the generated tokens for a single subscription. Subscribing to another package is possible, but the card must be registered again, which regenerates the appropriate tokens.

¶Information about Recurring Tokens

After a recurring card registration payment, the plugin generates a token that the merchant can use later to initiate the charge (e.g., when the subscription renewal is due).

A few important notes about the tokens:

• A separate token is registered for each subscription
• Protecting the database and properly storing the data is the responsibility of the merchant
• Token-based payment is tied to a WooCommerce Subscriptions event, not initiated by the Barion plugin
• Proper configuration of the WooCommerce Subscriptions plugin is the responsibility of the merchant. We recommend replacing WP-CRON with a properly configured server-side solution. More information: https://developer.wordpress.org/plugins/cron/
• If the subscription expires or is canceled, the token is deleted
• If the subscriber wishes to continue a subscription with an expired or permanently interrupted payment, a new token will be registered, thus the subscription will become active again

¶Integrated Apple Pay

From version v1.3.0, the plugin supports integrated Apple Pay payments on store fronts. While it was previously possible to pay with Apple Pay through Barion, this new development allows users to do so directly within your store, without redirection, essentially with a single (fingerprint or facial recognition) authentication.

¶Technical requirements and settings

Apple Pay is only available on the WooCommerce Block Checkout interface, as the classic checkout view does not support express payment methods! This is a constraint we had to adhere to because we see the old Woo payment interface as technically outdated.

Good to know: WooCommerce currently offers two different - and technically fundamentally different - payment interfaces. Each has its own advantages and disadvantages. In this case, the "express payment method" is what allows us to implement Apple Pay sustainably and reliably.

Towards integration, only a few steps are needed:

1. In the Barion admin interface, under the merchant settings in the Apple Pay section, register the domain (e.g., my-shop.com or apple-pay.my-shop.com) where you want to use the payment method.
2. Download the updated Well-known file, then upload it to the appropriate location on the server. The target path will be a .well-known folder in the "document root," making this file publicly accessible.
3. Complete the domain registration in the admin interface.
4. Copy the merchant's Public Identifier, which can be found in the merchant details.

After this, the plugin settings need to be configured:

1. Enable the Apple Pay payment method within the plugin
2. Enter the previously copied Public Identifier into the Apple Pay Merchant ID field
3. Save the settings

¶Sandbox and testing

More detailed information can be found on the Apple website.

1. For testing, you need an Apple device. Preferably choose a device that you can use exclusively for this purpose, as you need to log in with a sandbox Apple account to ensure no data is lost.
2. Contact Barion to create a sandbox Apple account. You need to provide an email address that you have access to but is not yet registered in the Apple system, neither in the live nor sandbox environment.
3. Barion will then create the account and send you the generated password.
4. The email address must be verified, so Apple will send a confirmation email to the provided address.
5. Log in to the device with the sandbox account.
6. Add a test card to the Wallet (you can choose from several test cards at the link above).
7. Start testing!

¶Apple Pay button customization

The Apple Pay button can be customized using CSS:

<style>
    apple-pay-button {
        --apple-pay-button-width: 140px;
        --apple-pay-button-height: 30px;
        --apple-pay-button-border-radius: 5px;
        --apple-pay-button-padding: 5px 0px;
    }
</style>

The CSS can be easily placed in the <head> section or in the style.css file. It can also be pasted into the Customize -> Additional CSS section without the style tag.

¶Limitations

Apple Pay payments do not support recurring payments.

More (primarily technical) information: https://docs.barion.com/Apple_Pay

¶Integrated Google Pay

From version v1.4.0, the plugin supports integrated Google Pay payments on the store front. While it was previously possible to pay with Google Pay through Barion, this new development allows users to do so directly within your store, without redirection, essentially with a single (fingerprint or facial recognition) authentication.

¶Technical requirements and settings

Google Pay is only available on the WooCommerce Block Checkout interface, as the classic checkout view does not support express payment methods! This is a restriction we had to adhere to because we see that the old Woo payment interface is technically outdated.

The Google Pay merchant ID can be found in the Barion admin interface, under the merchant settings, in the Google Pay section. This needs to be copied:

After this, the plugin settings need to be configured:

1. Enable the Google Pay payment method within the plugin
2. Enter the previously copied Google Pay Merchant ID into the appropriate field
3. Save the settings

¶Sandbox and testing

If the plugin is used in sandbox mode, Google Pay will also operate in sandbox mode. During payment, you can choose from the test cards on the Google Pay interface.

More (primarily technical) information: https://docs.barion.com/Google_Pay

¶Hook Index

The plugin provides the ability to control its operation through filters. By using hooks appropriately, you can even implement quite unique solutions.

¶barion-woocommerce_icon (Filter)

If you want to override the default Barion logo on the "Checkout" page, you can do so using the barion-woocommerce_icon filter:

add_filter('barion-woocommerce_icon', function (string $url): string {
    return $url;
});

¶barion-woocommerce_order_ref (Filter)

The plugin passes the order key to Barion (e.g., wc_order_q6MXBjFKQwm7B), which is completely unique. If you want to modify this, you can do so using the barion-woocommerce_order_ref filter:

add_filter('barion-woocommerce_order_ref', function (string $ref, WC_Order $order): string {
    return 'xyz-'.$order->get_order_number();
}, 10, 2);

¶barion-woocommerce_payment_cancelled_order_status (Filter)

After a cancelled payment, the plugin sets the order status to pending. If you want to modify this, you can do so using the barion-woocommerce_payment_cancelled_order_status filter:

add_filter('barion-woocommerce_payment_cancelled_order_status', function (string $status, WC_Order $order): string {
    return 'pending';
}, 10, 2);

¶barion-woocommerce_payment_failed_order_status (Filter)

After a failed payment, the plugin sets the order status to failed. If you want to modify this, you can do so using the barion-woocommerce_payment_failed_order_status filter:

add_filter('barion-woocommerce_payment_failed_order_status', function (string $status, WC_Order $order): string {
    return 'failed';
}, 10, 2);

¶barion-woocommerce_payment_expired_order_status (Filter)

After a payment timeout, the plugin sets the order status to cancelled. If you want to modify this, you can do so using the barion-woocommerce_payment_expired_order_status filter:

add_filter('barion-woocommerce_payment_expired_order_status', function (string $status, WC_Order $order): string {
    return 'cancelled';
}, 10, 2);

¶barion-woocommerce_payment_timeout (Filter)

The default payment timeout is 30 minutes. If you want to modify this, you can do so using the barion-woocommerce_payment_timeout filter:

add_filter('barion-woocommerce_payment_timeout', function (string $value, WC_Order $order): string {
    return '0.00:30:00';
}, 10, 2);

Only ISO 8601 compatible TimeSpan format can be given: D.HH:MM:SS.

¶barion-woocommerce_reservation_timeout (Filter)

In the case of two-step payment, the default value of the reservation timeout is 7 days. If you want to modify this, you can do so using the barion-woocommerce_reservation_timeout filter:

add_filter('barion-woocommerce_reservation_timeout', function (string $value, WC_Order $order): string {
    return '7.00:00:00';
}, 10, 2);

Only ISO 8601 compatible TimeSpan format can be given: D.HH:MM:SS.

¶barion-woocommerce_reservable (Filter)

The two-step payment enablement is available from the admin interface. If you want to decide this based on the order or other custom logic, you can do so using the barion-woocommerce_reservable filter:

add_filter('barion-woocommerce_reservable', function (bool $value, WC_Order $order): bool {
    return $order->get_total() > 10000;
}, 10, 2);

¶barion-woocommerce_hidden_mode (Filter)

The plugin provides the ability to make the payment gateway visible only to administrators on the checkout page. If you want to modify this logic, you can do so using the barion-woocommerce_hidden_mode filter:

add_filter('barion-woocommerce_hidden_mode', function (bool $hidden): bool {
    return ! is_user_logged_in();
});