VibeFox Paytrail for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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

Internet access to your shop: Paytrail confirms every payment with a server-to-server callback, so the shop should be reachable from the internet. Without callbacks, orders are still created 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Paytrail Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. To try the module first, turn on Test mode. For real payments, turn it off and enter your Merchant ID and Secret key. No callback URL has to be configured in Paytrail.

5. Turn on Enable/Disable and click Save.

On install the module creates two order statuses, Awaiting Paytrail payment and Paytrail payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows Test mode is active. Payments use the public Paytrail test account — no real money is charged. while test mode is on. In live mode it warns you when the merchant ID or secret key is missing, or when the merchant ID is the public test account 375917. It also warns you when the shop currency is not EUR. In all these cases Paytrail is not shown at checkout.

When you save, a merchant ID that contains anything other than digits is not saved: the error Paytrail merchant ID must contain digits only. The previous value was kept. is shown. The Title cannot be empty.

Paytrail

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

Title: the title displayed to customers during checkout. It is also the payment method name stored in the order. Default: Paytrail. Required.

Description: the text displayed to customers under the payment method 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). The section links to the Merchant Panel. Only EUR payments are supported.

Test mode: uses Paytrail's public test account (merchant ID 375917) for new payments instead of your own credentials. No real money is charged, and no keys are needed. Customers see Test mode: no real payment will be made. under the payment method. The secret key of the test account is public, so anyone could simulate a payment made 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. The saved key is never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secret key: tick Secret key and click Save to remove the saved key. An empty field keeps the saved value.

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

Callback URL: shows the URL at which Paytrail confirms every payment server-to-server. With friendly URLs it looks like https://your-shop/module/wcp_paytrail_gateway/callback. It is sent with each payment, so nothing has to be configured in the Paytrail panel, but the shop must be reachable from the internet.

Order status after payment: the status of a paid order.

Pending payments wait in Awaiting Paytrail payment. Amount mismatches and other problems always go to Paytrail payment on hold.

Advanced

Debug log: logs API requests and callbacks to logs/ptg_debug.log.php in the module folder. The file cannot be opened from the web. Personal data and keys are not logged. Errors and warnings are always logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the settings and the log. Disabling the module never deletes anything. The Paytrail transaction data of orders is always kept, because refunds of old orders need it. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Paytrail) and confirms. The module creates a Paytrail payment for the cart total in euros and sends the order rows with it: products after cart rules, shipping and gift wrapping, 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 cart language. No order exists yet at this point.

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 shop 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 an attempt created for that cart. The paid amount is compared with the cart total. The order is marked paid only after Paytrail confirms it this way. The module handles these Paytrail statuses:

After a successful payment the customer sees the standard order confirmation page with Your Paytrail payment has been received. For a pending payment the page shows Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. If the callback is recording the payment at the same moment, a Payment confirmation page asks the customer not to pay again and offers a Check again button.

After a cancelled or failed payment the customer is back at checkout with 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. The cart is kept. A return that cannot be verified shows Payment verification failed. and changes nothing.

If Paytrail cannot start the payment, the customer stays at checkout with 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 written to the log. A total outside Paytrail's limits gives This order total cannot be paid with Paytrail. Please choose another payment method.

A Paytrail payment cannot be cancelled through the API. Each new attempt for the cart is a new Paytrail payment. If the customer also pays an older, still open payment page, the second payment is reported on the order as a duplicate to refund.

The callback works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

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

Orders and refunds

Order statuses

No order yet: the customer was sent to Paytrail and has not paid, or Paytrail has not confirmed the payment yet. Only the cart exists.

Payment accepted or Delivered: the payment was confirmed. The status follows Order status after payment. The payment is recorded with the Paytrail transaction ID, and a note shows the transaction, the payment method used at Paytrail and the amount.

Awaiting Paytrail payment: the payment is pending at the provider (invoice or delayed payment). The order moves to the paid status when Paytrail confirms the payment, or to Payment error when it fails.

Paytrail payment on hold: the paid amount differs from the order total (the amount actually paid is recorded), the payment arrived after the order had been cancelled, or a test payment was received while the shop is live (no real money, nothing recorded). The note explains the reason. Check the order, then process it or refund the payment.

Payment error: a pending payment failed or was cancelled.

Refunded: the payment was fully refunded through the module.

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

Paytrail payment block

The order page shows a Paytrail payment block with the transaction ID, the mode (a TEST mode badge for test payments), the payment method, the Paytrail status, the amount paid and refunded, the refund form, the refund history, the payment attempts of the cart and the Paytrail notes of the order.

Refunds

In the Paytrail payment block enter the amount (the amount not refunded yet is filled in), optionally a reason for the order note, and click Refund via Paytrail. Confirm the question Refund this amount through Paytrail? This cannot be undone. Full and partial refunds are supported, for amounts only. You need the right to edit orders; access to the Modules pages is not needed. You can refund up to the amount Paytrail actually took, so after an amount mismatch the limit is what the customer paid, not the order total. The refund uses the credentials of the mode the payment was made in, so for a live payment the live credentials must be set. Refunds are available once Paytrail has confirmed the payment.

If the payment method does not support direct refunds, the module starts an e-mail refund automatically: Paytrail e-mails the customer to enter a bank account. This needs the customer's e-mail on the order. The 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, and the refund no longer counts as refunded; refund the customer another way. If Paytrail rejects the refund right away, the block shows the error and no refund is recorded. A full refund sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Paytrail. Refunds made in the Paytrail Merchant Panel are not synchronized back to PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paytrail Gateway is the first block on Modules > Module Manager > VibeFox Paytrail Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-paytrail and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed by the callbacks and the customer return, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 (not the public test account 375917). Check that the cart currency is EUR. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows a warning for missing credentials and a wrong shop currency.

The payment went through, but no order was created: the callback cannot reach your shop, and the customer did not come back to the shop. The Callback URL shown in the Orders section must be reachable from the internet (no 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 cart. Nothing is changed. Check that the Secret key is correct and belongs to the Merchant ID.

Callback answers Temporarily unavailable: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Paytrail calls again. Look at the Log field for the reason.

The customer sees an error when choosing Paytrail: look at the Log field on the module page. For example, Paytrail API error (401) means wrong credentials. Turn on Debug log for more details.

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

Order is Paytrail payment on hold: read the notes in the Paytrail payment block. The reason is 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. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. means the payment was made in live mode and the live credentials are not set. Invalid refund amount: at most … means the amount is larger than what is left to refund. If the payment method supports only e-mail refunds, the order needs the customer's e-mail.

Developer hook: the actionWcpPaytrailPaymentRequest hook changes the payment request before it is signed and sent.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Paytrail Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the log are removed. If it is off, all settings are kept for a later re-install. The Paytrail transactions and refunds and the order statuses Awaiting Paytrail payment and Paytrail payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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