Toret Fio plugin documentation

You are on the documentation page for the Toret Fio plugin, which integrates the automatic payment verification service from Fio Banka and the payment gateway of the same name into your e-shop. You can purchase the Fio plugin here: Toret Fio for WooCommerce

Plugin Installation

Upon purchasing the plugin, you will receive a license key and a download link for the plugin zip file via email. You can find detailed instructions on how to install the plugin from your computer into WordPress here.

Plugin Activation

After installing the plugin, open the Toret Fio plugin (Toret plugins → Toret Fio), insert the license key into the appropriate field, and activate it with the  Ověřit licenci (Verify License) button.

Bank Transfer Payment Pairing

1. Connecting the Plugin with Bank Account

For the plugin to pair with the bank account, it is necessary to generate a token in internet banking. You can generate it in Settings → API → Add new token.

It is possible to pair multiple accounts at once with the plugin. For example, if customers pay to different accounts according to currency. You can check payments on a CZK account and an EUR account simultaneously with the plugin.

2. Setting Order Status After Payment Pairing

In the next step, it is important to select the order status to which the order will automatically switch after it is paired with a payment. For pairing to occur, the variable symbol must match the set order source, and the order amount must match the payment amount. You can set the status separately for physical and virtual products.

3. Payment Pairing by Variable Symbol

For orders to pair with payment, the variable symbol (VS) in the payment must match the source set in the plugin, e.g., the order number. If the VS and amount match, the payment is paired with the order, and the order status changes. For Slovak customers, the payment note is automatically checked. Slovak customers do not have the option to enter a variable symbol.

You can pair VS by Order ID, Order Number, supported numbering plugins Toret Order Number and WooCommerce Sequential Order Number. If none of the options for pairing the variable symbol suits you, you can pair a custom field. Insert the value of the custom field for retrieving the variable symbol into the plugin settings.

If you want to check the VS of payments from multiple sources, you can set a backup field for payment pairing. Set the ID of the custom field from which the plugin should retrieve the variable symbol value into the appropriate function. 

If the variable number is too short, banks add zeros before it, and payment pairing may fail. Activating the function Automaticky odstranit počáteční nuly z variabilního čísla (Automatically remove leading zeros from variable number) will prevent this failure.

4. Loading Payments and Setting Paid Order Verification

There are two options for loading and updating payments.

The first option, which we recommend, is loading and updating payments using a CRON URL. Every e-shop has its own CRON URL, which you can find in the Fio plugin settings. You set up CRON on your hosting with an interval that suits you so that payments are regularly checked against orders. For example, you can set it to run every hour. This ensures that payments are checked against orders every hour, and if a payment matches an order, the order status changes according to the previous setting.

The second option is automatic checking using a WordPress function. We do not recommend this option because it can be affected by caching or security plugins. If you choose the automatic loading option using a WordPress function, you also need to set the number of hours after which the list will be updated in the plugin.

For both payment update options, it is also necessary to set the number of days back, i.e., how far back payments will be loaded. This limits the check to a specific time period and avoids checking all orders on the e-shop.

5. Notification

Setting the Notification function is not mandatory for the plugin functionality, but we definitely recommend setting it. Set an email address in the function to which you will receive an email if the payment does not match the amount in the order. For example, the customer sends a lower or higher payment.

Notification of payment mismatch with order value:

Notification of incorrect payment:

Tip: The order number in the email notification takes you directly to the order detail.

6. Table with Loaded Payments

At the end of the plugin settings, you will find a table with loaded account movements. This is a table of payments that have been loaded from your account using the plugin. As mentioned, the order status only changes if the amount and VS symbol match the order. If the amount differs, or the variable symbol is entered incorrectly or not filled in at all, the payment is not paired with the order, and the order status does not change.

For better clarity, individual payments are color-coded according to the relationship between the payment and the order.

• White background – Not paired
• Green background – Paired and everything matches
• Orange background – Not paired, amount does not match

The table also contains a filter with which you can filter individual payments. You can list payments that are in the status: Paired, Not paired, Underpaid, Overpaid.

In case you are loading payments from multiple accounts, you can switch the overview in the table by token.

Tip: If the order is not paired due to an incorrect amount, you can click on the order number in the “OBJEDNÁVKA” (ORDER) column and go directly to its detail.

Fio Payment Gateway

The Toret Fio plugin also includes the option to set up a payment gateway if you have contracted it with Fio banka.

You can find the payment gateway settings in WooCommerce → Settings → Payments → Platební brána Fio (Fio Payment Gateway).

For correct implementation of the Fio payment gateway on your e-shop, you will need to have a signed contract. In case you have everything settled, you will receive access to the test interface via email. The Fio payment gateway is powered by GP Webpay. The integration of the payment gateway is therefore identical to the GP Webpay payment gateway plugin.

Connecting the Plugin with the Payment Gateway

Below you will find the steps described for creating, downloading, and uploading keys to the GP Webpay environment and WordPress.

Once you perform test payments (you will have the test card number in the email or find it here) and GP Webpay confirms that everything is fine, you will receive a production key. Now you will have to repeat the entire process in the production environment – upload the key again to the GP Webpay environment and WordPress, adjust the key name setting in the plugin, and finally turn off the Test checkbox in the plugin settings.

Detailed instructions below ↓

1. Logging into the Test Environment.

You can find the login at https://test.portal.gpwebpay.com/, but the URL including login will also arrive in your email.

After logging in, you will be prompted to confirm details and change the generated password. A code for confirming the change will be sent to your email.

2. Creating and Saving a Test Key

Log in again and generate a private key.

Private Key

Creating and uploading a private key consists of several steps. First, go to the Správa klíčů (Key Management) section and click on Vytvořit (Create).

In the next step, create any password for the key, which you should note down; you will need it further in the GP Webpay account and when setting up the plugin, see Plugin Settings and Options.

After creation, the key will be downloaded to your computer.

Now you can save the key directly to the browser memory. Return to the Správa klíčů (Key Management) section and click on the e-shop.

Here you must insert the key that was downloaded to your computer.

When inserting the private key into the browser memory, select the option Trvale (Permanently) → via the Vybrat soubor (Select File) button insert the downloaded key → fill in the password you created in the previous step → insert the key with the button.

Subsequently, it is necessary to upload the key to the WordPress directory. Use the “Nahrát privátní klíč” (Upload private key) function in the plugin settings for this. 

3. Setting Access Credentials in the Plugin

After creating keys in the GP Webpay administration, go to the Fio plugin settings, which you can find in Toret plugins > Toret Fio. Here you must insert the access credentials to connect the plugin with the payment gateway.

Testovací mód (Test Mode) – activate/deactivate the test environment in this checkbox

Číslo obchodníka (Merchant Number) – enter the merchant number assigned to you in this field

Heslo privátního klíče (Private Key Password) – here you enter the password you created for the key

Nahrát privátní klíč (Upload Private Key) – upload the created private key via the “select file” button

Finally, do not forget to save the changes made. Subsequently, it is possible to proceed to the payment method settings.

4. Payment Method Settings

Set the payment method in WooCommerce > Settings > Payments. The payment method Platební brána Fio (Fio Payment Gateway) is a grouped payment method through which all payment methods available for your payment gateway can be configured. This method is compatible only with the default WooCommerce checkout.

If you use a checkout with blocks (Gutenberg checkout) in your e-shop, you need to set up separate payment methods (e.g., Fio: Payment Card, Fio: Moneta Bank, etc.)

Grouped Payment Method Settings

This is the Fio Payment Gateway payment method. This payment method is compatible only with the default WooCommerce checkout, and all available payment methods for this payment gateway can be set through it.

1.  Povolit/Zakázat (Enable/Disable) – by checking this box, you determine whether customers will have this payment method available on the Checkout page or not

2. Titulek (Title) –  here you can edit the payment method name as it will be displayed when selecting the payment method at checkout

3. Popis (Description) – in this field, you can describe the payment instructions for the customer

4. Ikona platební metody (Payment Method Icon) – if you want a custom payment method icon, enter its URL here. Otherwise, the default icon from the plugin is set.

 5. Povolit způsob dopravy (Allow Shipping Method) –  if you want to allow all shipping methods, leave this field empty. Alternatively, you can define only certain shipping methods for the payment gateway.

6. Povolit Fio pro země (Allow Fio for Countries) – specify for which countries the gateway will be available

7. Povolit platební metody (Enable Payment Methods) – here enter which payment methods available for the payment gateway you want to offer to customers

10. Instrukce (Instructions) – write payment instructions here, which will be displayed on the Thank You page and confirmation email

After filling in the details, don’t forget to click the Uložit změny (Save Changes) button.

Separate Payment Methods Settings

Separate payment methods (e.g., Fio: Payment Card, Fio: Moneta Bank, etc.) need to be set if you use a checkout with blocks (Gutenberg checkout). Perform the settings similarly for all methods you want to offer at checkout.

1. Titulek (Title) –  here you can edit the payment method name as it will be displayed when selecting the payment method at checkout

2. Povolit/Zakázat (Enable/Disable) – by checking this box, you determine whether customers will have this payment method available on the Checkout page or not

3. Popis (Description) – in this field, you can describe the payment instructions for the customer

4. Povolit způsob dopravy (Allow Shipping Method) –  if you want to allow all shipping methods, leave this field empty. Alternatively, you can define only certain shipping methods for the payment gateway.

5. Dostupné země (Available Countries) – specify for which countries the gateway will be available

6. Ikona platební metody (Payment Method Icon) – if you want a custom payment method icon, enter its URL here. Otherwise, the default icon from the plugin is set.

Do not forget to save the changes made. Perform this setting for all methods you want to offer at checkout.

5. Testing

After setting up integration and plugin settings, perform test payments with a test payment card:

Card Number: 4056070000000016
Card Validity: 12/2025
CVC2: 442

6. Transition to Production Environment

After successful integration of the e-shop in the test environment, write to the email gpwebpay@gpe.cz. The payment gateway will send you an email with access to the production environment, where you will create a new production private key (similar to step 2).

You will have to upload the new integration key again via the Fio plugin settings to the WordPress directory. In case you chose a new password for the private key, save the new password in the plugin as well and then turn off the Test checkbox in the plugin settings (see step 3).

Private Key

Automatic Payment Status Loading

Upon payment completion, the customer is redirected to the thank you page. At the same time, a notification that the order has been paid is transmitted, and the order status changes to Processing (for physical products) or Completed (for virtual products).

However, it may happen that the customer was not redirected to the thank you page for some reason after paying for the order. In that case, the plugin has no information from the payment gateway that the order has been paid. To prevent paid orders without notification from being cancelled by WooCommerce functionality, it is necessary to set up the automatic payment status loading function.

You can find the automatic payment status loading settings under the tab Toret Plugin → Toret Fio. 

Toret Fio – Automatic payment status loading

1) Set the number of days for retrospective payment status checks, i.e., in what retrospective time horizon orders will be checked.

Toret Fio – setting number of days for retrospective check

2) If you do not want to check the payment status for all orders, you can select individual order statuses to exclude from the check. We definitely do not recommend excluding Pending Payment, Failed, and Cancelled statuses.

Toret Fio – setting order statuses that will not be checked

3) Change order status based on payment status. If you want to change the status, e.g., to “Processing” or another preferred status after confirming payment of the order, set the order status to which the order will switch for the payment status “Požadavek na stržení” (Request for deduction). In payment status “Request for deduction”, the order is considered paid.

Toret Fio – changing order status based on payment status

The function for changing the order status based on the payment status must be enabled by activating the checkbox.

Toret Fio – activating order status change based on payment status

4) For payment statuses to update according to the settings from the previous three points, you must set the CRON URL listed in your site settings on your hosting. We recommend running CRON regularly, at least once per hour.

Toret FIO – CRON settings

Test Payment Card

Card Number: 4056070000000016
Card Validity: 12/2025
CVC2: 442

FAQ

Switching Order Status to Custom Status

To set switching the order status to a custom status, use the filter below in function.php in the child theme so that the filter is not deleted during updates.

$status_set = apply_filters( ‚fio_set_status‘, $option[‚order‘], $order );

How to Set Pairing with Custom Order Numbering?

For custom order pairing, you need to insert the name of the custom field containing the new order number into the plugin.

Example:

Booster for WooCommerce –  _wcj_order_number 

Filters

Expanding Order Statuses

In case you need to somehow influence the expansion of order statuses for which payment status will not be checked, the following filter was added:

$statuses = array(
'completed',
'failed',
'cancelled',
'refunded'
);
return apply_filters( 'fio_blocked_order_statuses', $statuses );
add_filter( 'fio_blocked_order_statuses', 'extend_fio_blocked_order_statuses' );
function extend_fio_blocked_order_statuses( $statuses ){
$statuses[] = 'nezaplaceno'; // unpaid
return $statuses;
}

Filter for Changing Order Status After Payment Pairing

After pairing the order with payment, it is possible to automatically change the status via the FIO plugin to Processing (Zpracovává se) or Completed (Dokončeno). In case you use custom order statuses and want to change the order to a custom status after pairing the payment, you need to modify the plugin using a filter.

Filter definition here:

$status_set = apply_filters( ‚fio_set_status‘, ‚processing‘, $order );

Filter example:

add_filter( 'fio_set_status', 'fio_set_status_function', 1, 2 );
if( !function_exists( 'fio_set_status_function' ) ){
function fio_set_status_function( $status , $order ){
return 'completed';
}
}

Use the custom status slug instead of the value completed .

Insert the filter into the child theme’s functions.php or into an empty plugin e.g. Boilerplate.