VibeFox Paytrail for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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

Internet access to your store: Paytrail confirms every payment with a server-to-server callback, so the store 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_paytrail_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_paytrail_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_paytrail_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Paytrail Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. To try the extension 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_paytrail_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Paytrail Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Paytrail settings as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the callback URL is different (see Orders).

A new install starts with the payment method turned off and test mode off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Paytrail Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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; in these cases Paytrail is not shown at checkout. It also warns you when the default currency of the store is not EUR: Paytrail is then shown only when the customer pays in EUR. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty or longer than 128 characters, Sort Order must be a whole number (negative numbers are allowed), Total must be a number, 0 or greater, and the geo zone and order statuses must exist; otherwise nothing is saved. 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, and the other settings are saved.

Paytrail

The section starts with a short note about the Paytrail payment page and the rule that the order gets its status only after Paytrail has confirmed the payment.

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, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button, next to the Paytrail icon. Default: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

Sort Order: the position of Paytrail among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Paytrail only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Paytrail is offered. Leave it empty to offer Paytrail for any total.

API credentials

Your merchant ID and secret key are shown in the Paytrail Merchant Panel (account or integration details). The section links to Paytrail. 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. at the Confirm Order step. 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 store. Default: off.

Merchant ID: your Paytrail merchant ID (digits only). Used when test mode is off. Unlike the secret key, it is shown on the page after saving.

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. To remove the saved key, tick Clear saved secret key under the field and click Save.

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

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Paytrail has confirmed the payment. Each status field below lists your OpenCart order statuses.

Callback URL: shows the URL at which Paytrail confirms every payment server-to-server. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_paytrail_gateway/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_paytrail_gateway/payment/wcp_paytrail_gateway.callback. It is sent with each payment, so nothing has to be configured in the Paytrail panel, but the store must be reachable from the internet.

Order status after payment: the status of a paid order. Default: Processing. Select Complete if every paid order should be completed at once.

Awaiting payment status: Paytrail reports the payment as pending or delayed (an invoice or instalment waiting for approval of the provider). The order is updated automatically when Paytrail confirms or rejects it. Default: Pending.

Payment on hold status: the payment needs your attention (see Order statuses). Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Payment failed status: set when an awaiting Paytrail payment fails. Default: Failed.

Refunded status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug log: logs API requests and callbacks to ptg_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to ptg_debug.old.log.php. 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 extension removes the gateway settings and the log. Disabling the extension never deletes anything. The Paytrail transaction data of orders is always kept, because refunds of old orders need it. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The merchant ID and the secret key are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved merchant ID and secret key are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Paytrail). At the Confirm Order step the customer sees the Paytrail icon and your description. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension creates a Paytrail payment for the order total in euros with the order number as the reference and sends the order rows with it: products with their options and tax, gift certificates bought, shipping and other charges. Coupons, store credit, reward points and used gift certificates are spread over the rows. The rows always add up to the payment amount; a rounding difference is folded into a row or sent as a Rounding row. The customer's contact details are sent, and billing and delivery addresses only when they are complete. The payment page language is Finnish, Swedish or English, following the customer's language.

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 an 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, and then gets its status the standard OpenCart way, with the usual order e-mails and stock update. The extension handles these Paytrail statuses:

After a successful payment the customer sees the OpenCart order success 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 Check again.

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. On OpenCart 4 these messages are shown above the checkout page. A return that cannot be verified shows a Payment Error page with Payment verification failed. and changes nothing.

If Paytrail cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, 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.

OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout (a new attempt pays the same order). If the cart was already paid with another order, the customer goes straight to the success page and no new payment is started. A Paytrail payment cannot be cancelled through the API, so an older payment page stays payable. If the customer pays it as well, the second payment is reported on the paid order as a duplicate to refund, and the other order stays without a status. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example you cancelled it), the customer is sent back to the checkout with the message Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. If its awaiting payment failed, the message is The Paytrail payment was cancelled or failed. You can try again or choose another payment method. The next Confirm Order pays a new order. If that order was already paid for an earlier cart and the cart has changed since, the customer is taken back to the checkout, and the next Confirm Order pays a new order of the current cart. A closed order is never shown as paid.

The callback also works while the store is in maintenance mode, because OpenCart lets payment extension requests through (on OpenCart 4 the extension adds its own startup action for this, which also lets the customer return from Paytrail).

The customer chooses the payment method on the Paytrail page, not in your checkout. The extension 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 status (missing order): the customer was sent to Paytrail and has not paid, the payment failed, or Paytrail has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order status after payment (default Processing): the payment was confirmed. A note shows the Paytrail transaction, the payment method used at Paytrail and the amount, with TEST mode — no real money. for test payments.

Awaiting payment status (default Pending): 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 the failed status when it fails.

Payment on hold status (default Pending): the paid amount differs from the order total (the amount actually paid is recorded), the payment arrived after the order had been set to another status, for example cancelled, or a test payment was received while the extension is in live mode (no real money, nothing to refund). The note explains the reason. Check the order, then process it or refund the payment.

Payment failed status (default Failed): a pending payment failed or was cancelled.

Refunded status (default Refunded): the payment was fully refunded through the extension.

Repeated or parallel callbacks are applied once, without duplicate notes. A paid, refunded or completed order is never reopened by a later callback. If a second attempt of an already paid order or cart is paid, the order is not changed; a Duplicate payment note asks you to refund it in the Paytrail Merchant Panel.

Notes are entries in the order History that the customer does not see.

VibeFox Paytrail Gateway tab

In Sales > Orders open an order paid with Paytrail. At the bottom of the order page, next to History and Additional, the VibeFox Paytrail Gateway tab lists the payment attempts of the order (date, Paytrail transaction and stamp with a Test label for test payments, amount, payment method, Paytrail status and result), the amounts Paid / refunded, the refund form, the refund history and the Paytrail notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Paytrail Gateway tab 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 modify the extension (set in System > Users > User Groups). 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 extension 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 tab shows the error and no refund is recorded. A full refund sets the order to the Refunded status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

Product returns in Sales > Returns do not send money back through Paytrail. Refunds made in the Paytrail Merchant Panel are not synchronised back to OpenCart.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paytrail Gateway is the first block on Extensions > Extensions > Payments > VibeFox Paytrail Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-paytrail and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. 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 extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer pays in EUR, that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning for missing credentials and a store currency other than EUR.

The payment went through, but the order stays without a status: the callback cannot reach your store, 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 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. 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 status could not be set. Paytrail calls again. Look at the Log field for the reason.

The customer sees an error after Confirm Order: look at the Log field on the extension page. For example, Paytrail API error (401) means wrong credentials. Turn on Debug log for more details. This payment method is not available. Please reload the checkout page. means the payment method was turned off meanwhile or the checkout no longer matches the order.

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

The order is in the on hold status: read the notes in the VibeFox Paytrail Gateway tab. The reason is a different paid amount, a payment after a status change 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. This payment method supports only e-mail refunds, but the order has no billing e-mail. means the order needs the customer's e-mail.

For developers: before the payment request is signed and sent, the extension triggers the OpenCart event ptg_payment_request with the request and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Paytrail Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the callback and the customer's return through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, test mode, merchant ID, secret key, logging) and the log are removed. If it is off, they are kept for a later re-install. The Paytrail transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Paytrail Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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