VibeFox Paytrail for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: EUR. Paytrail accepts only euros. For any other currency the payment method is hidden at checkout. Amounts are sent in cents.

Internet access to your site: Paytrail confirms every payment with a server-to-server callback, so the site should be reachable from the internet. Without callbacks, orders are still confirmed when the customer returns from Paytrail.

Paytrail account: you need your merchant ID and secret key, shown in the Paytrail Merchant Panel (account or integration details). For testing no account is needed: test mode uses Paytrail's public test account. The payment methods themselves are enabled in your Paytrail account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_paytrail_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Paytrail > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. To try the plugin first, tick Test mode. For real payments, untick it and enter your Merchant ID and Secret key. No callback URL has to be configured in Paytrail.

6. Turn on Enable/Disable and save.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Paytrail. Above the fields the page shows Test mode is active. while test mode is on. In live mode it warns you when the merchant ID or secret key is missing, and it warns you when the store currency is not EUR. In both cases Paytrail is not shown at checkout. In the list of payment methods, Paytrail is marked as needing setup while live mode has no credentials.

When you save, a merchant ID that contains anything other than digits is not saved: an error is shown and the previous value is kept.

General

Enable/Disable: Enable Paytrail turns the payment method on or off. Default: off.

Title: the title displayed to customers during checkout. Default: Paytrail.

Description: the text displayed to customers during checkout. Default: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API credentials

Your merchant ID and secret key are shown in the Paytrail Merchant Panel (account or integration details). Only EUR payments are supported.

Test mode: Use the Paytrail test account. New payments use Paytrail's public test account (merchant ID 375917) instead of your own credentials. No real money is charged. Customers see Test mode: no real payment will be made. at checkout. The secret key of the test account is public, so anyone could simulate a payment for an order created in test mode. Never keep test mode on in a live shop. Default: off.

Merchant ID: your Paytrail merchant ID (digits only). Used when test mode is off.

Secret key: your Paytrail secret key. Used when test mode is off.

Callbacks and refunds always use the credentials of the mode the payment was made in, so switching between test and live does not break older orders.

Orders

This section shows the callback URL, which looks like https://your-site/wc-api/ptg_paytrail/. Paytrail confirms every payment server-to-server at this URL. It is sent with each payment, so nothing has to be configured in the Paytrail panel, but the site must be reachable from the internet.

Order status after payment: the status of a paid order. The status is set in one step, so the customer gets one set of e-mails.

Processing: the WooCommerce default (default). Orders with only virtual or downloadable items are completed by WooCommerce anyway.

Completed: every paid order becomes Completed.

Advanced

Debug log: Log API requests and callbacks. Written to WooCommerce > Status > Logs, source wcp_paytrail_gateway, without personal data or keys. Errors are always logged. Default: off.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. Deactivating the plugin never deletes anything. Without the Paytrail transaction data, refunds of old orders are no longer possible from WooCommerce. Default: off.

Checkout

The customer chooses the payment method (by default Paytrail) and places the order. The plugin creates a Paytrail payment for the order total in euros and sends the order rows with it: products, shipping and fees, each with its VAT rate to one decimal. The rows always add up to the payment amount; a rounding difference is folded into a row or sent as a Rounding row. Billing and delivery addresses are sent only when they are complete, and long values are shortened to Paytrail's limits. The payment page language is Finnish, Swedish or English, following the store locale.

The customer is sent to the Paytrail payment page, chooses a payment method enabled for your Paytrail account and pays. Paytrail then confirms the payment twice: it sends the customer back to your store and calls the callback URL server-to-server. Both are accepted only with a valid signature made with the credentials of that payment attempt, and only for the attempt created for that order. The paid amount is compared with the order total. The order is marked paid only after Paytrail confirms it this way. The plugin handles these Paytrail statuses:

ok: the payment was made. The order is marked paid when the amount matches.

pending, delayed: the payment waits for the payment provider, for example an invoice approval. The order is put on hold until Paytrail confirms it.

fail: the payment failed or was cancelled. An unpaid order of the latest attempt is marked Failed. Paid orders are never changed.

After a successful payment the customer sees the order received page. After a cancelled or failed payment the customer goes to the Pay for order page with the message The Paytrail payment was cancelled or failed. You can try again or choose another payment method. If the payment is not finished yet, the message is The Paytrail payment has not been completed yet. You can try again or choose another payment method.

If Paytrail cannot start the payment, the customer sees a short message, for example Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (wrong credentials) or Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. The technical reason is added to the order notes and the log. Orders above Paytrail's maximum amount cannot be paid with Paytrail.

A Paytrail payment cannot be cancelled through the API. If the customer starts a new payment and then also pays an older, still open payment page, the second payment is reported in the order notes as a duplicate to refund.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The customer chooses the payment method on the Paytrail page, not in your checkout. The plugin has no card tokenization or saved cards, no WooCommerce Subscriptions, no shop-in-shop, no manual invoice activation and no settlement reports.

Orders and refunds

Order statuses

Pending payment: the Paytrail payment was created and the customer has not paid yet. The order note shows the Paytrail transaction ID, the amount and the mode.

Processing or Completed: the payment was confirmed. The status follows Order status after payment. The order note shows the transaction, the payment method used at Paytrail and the amount. The transaction ID is the Paytrail transaction ID.

On hold: the payment is pending at the provider (invoice or delayed payment), the paid amount differs from the order total, the payment arrived after the order had been cancelled, or a test payment was received while the store is live (no real money). The order note explains the reason. Check the order, then process it or refund the payment.

Failed: the latest payment attempt failed or was cancelled by the customer. The customer can pay again.

Repeated or parallel callbacks never create duplicate notes, stock reductions or e-mails. If a second attempt of an already paid order is paid, the order is not changed again; a Duplicate payment note asks you to refund it in the Paytrail Merchant Panel.

Refunds

Open the order, click Refund, enter the amount and click Refund via Paytrail (the button shows your Title). Full and partial refunds are supported, for amounts only (no refund item rows). The button is available only for orders with a confirmed Paytrail payment. The refund uses the credentials of the mode the payment was made in, so for a live payment the live credentials must be set.

If the payment method does not support direct refunds, the plugin starts an e-mail refund automatically: Paytrail e-mails the customer to enter a bank account. This needs a billing e-mail on the order. The order note says which kind of refund was started.

A refund can be completed at once or be processed later. Paytrail's later confirmation is added as a note. If Paytrail could not complete the refund, a note says that the money was not returned to the customer: refund it another way and delete the WooCommerce refund. If Paytrail rejects the refund right away, WooCommerce shows the error and no refund is recorded.

Refunds made in the Paytrail Merchant Panel are not synchronized back to WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Paytrail. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Paytrail is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Paytrail does not appear at checkout: check that the license is active, Enable/Disable is on and either Test mode is on or Merchant ID and Secret key are filled in. Check that the store currency (or the order currency on the Pay for order page) is EUR. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: the callback cannot reach your site, and the customer did not come back to the store. The callback URL shown in the Orders section must be reachable from the internet (no maintenance mode, basic authentication or firewall in the way).

Callback or return answers Payment verification failed.: the signature is invalid, or the payment does not belong to a payment attempt of the order. The order is not changed. Check that the Secret key is correct and belongs to the Merchant ID.

The payment is not created: the order note and the log show the Paytrail error, for example Paytrail API error (401): … for wrong credentials. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_paytrail_gateway.

The merchant ID is not saved: it must contain digits only. Copy it again from the Paytrail Merchant Panel.

The order is On hold: read the order note. The reason is a pending or delayed payment, a different paid amount, a payment after cancellation or a test payment in live mode.

Refund fails: read the message. This order has no confirmed Paytrail payment. Refund it manually. means there is no confirmed Paytrail payment to refund. A message about missing live credentials means the payment was made in live mode and the live credentials are not set. If the payment method supports only e-mail refunds, the order needs a billing e-mail.

Developer hooks: the ptg_payment_request filter changes the payment request before it is signed and sent; the ptg_icon filter changes the checkout icon.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the log of this plugin and the Paytrail data stored on orders (payment attempts, transaction data, refund records) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs; without the Paytrail data, old orders can no longer be refunded from WooCommerce.

Paytrail is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Paytrail.