VibeFox Paytrail for Adobe Commerce — Help
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4.
Currency: EUR. Paytrail accepts only euros. For a cart in any other currency the payment method is hidden at checkout. The base currency of your store can be different; what counts is the currency the customer pays in. Amounts are sent in euro cents, from 0.01 to 999999.99 EUR.
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 a firewall or basic authentication in front of it. Without callbacks, orders are still confirmed when the customer returns from Paytrail.
Magento cron: the order e-mail of a paid order is sent by a cron job of the module, so the Magento cron must run.
Paytrail account: you need your merchant ID and secret key, shown in the Paytrail Merchant Panel. 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-paytrail-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PaytrailPayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_PaytrailPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Paytrail Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).
4. To try the module first, set Test mode to Yes, set Enable to Yes, click Save Config and place a test order in a store view with EUR as its currency. For real payments, set Test mode to No, enter your Merchant ID and Secret key and click Save Config. No callback URL has to be configured in Paytrail.
The module adds the Paytrail payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the Paytrail payment attempts, their events and the refunds.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Paytrail Gateway, in the standard Magento configuration form, one list of fields without sections. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete module data on uninstall is read for the default store view, so set it in the Default Config. Save Config saves the whole page.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Payment method title is required and must not exceed 128 characters.); a Sort order that is empty or not a whole number (Sort order must be a whole number.); a Minimum order total or Maximum order total that is not a number of 0 or greater (Order total limit must be a non-negative number.). Write amounts with a dot, for example 9.99; a comma is rejected.
A Merchant ID with anything other than digits is the exception: the other valid fields are saved, the previous merchant ID stays and a warning says Merchant ID must contain digits only. The previous merchant ID was retained; other valid fields were saved.
Enable: shows or hides Paytrail at checkout. It is shown only when the license is active, the cart currency is EUR and either Test mode is Yes or Merchant ID and Secret key are set. Default: No.
Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Paytrail. Required, at most 128 characters.
Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
Test mode: uses the public Paytrail 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 ENABLED. No real charges 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, and such an order is invoiced like a paid one. Never keep test mode on in a live store. Default: No.
Merchant ID: your Paytrail merchant ID, from the Paytrail Merchant Panel. Digits only. Used when Test mode is No. The public test merchant ID 375917 is not accepted for live payments: the payment method is then hidden at checkout.
Secret key: your Paytrail secret key, from the Paytrail Merchant Panel. Used when Test mode is No. Magento stores it encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.
Callbacks, returns and refunds always use the credentials of the mode the payment was started in. A payment made in live mode still needs the live Merchant ID and Secret key after you switch to test mode, so keep them until its payments and refunds are finished.
Order status after payment: the order state after a confirmed payment.
An order with nothing to ship becomes Complete in Magento with either setting. Pending payments leave the order in Pending Payment. Amount mismatches always put the order On Hold.
Logging: adds details about starting a payment to var/log/ptg_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at about 5 MB. Keys, e-mail addresses and known personal values of the customer are hidden in the log. Warnings and errors are always written, also while this is off. Default: No.
Delete module data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes, the private journals of payment attempts and refunds, the module cache and the log (see Uninstall). Native orders and accounting history are preserved. Default: No.
Payment from applicable countries: All Allowed Countries (default) offers Paytrail for every country your store allows, Specific Countries only for the countries below.
Payment from specific countries: offer Paytrail only for billing addresses in these countries.
Minimum order total: offer Paytrail only from this order total, in the base currency of your store. Leave it empty for no minimum.
Maximum order total: offer Paytrail only up to this order total, in the base currency. Leave it empty for no maximum; do not write 0.00.
Sort order: the position among the payment methods at checkout. A whole number. Default: 0.
Paytrail: this row shows Paytrail accepts EUR only. URLs for payment and refund callbacks are sent with each API request. and the note EUR only. Callback URLs are sent with every payment. Existing payments continue to use their original test or live mode. While Enable is Yes in the Default Config, it also shows the state of the Default Config: TEST mode uses the public account 375917. No real money., Live merchant ID and secret key are required. or The public test merchant ID cannot be used in live mode. The method is hidden.
Log: shows the size and the latest entries of the log, read-only. Click Clear log to empty it.
Checkout
At the payment step the customer chooses the payment method (by default Paytrail) and sees the description and the note You will be redirected to Paytrail to pay. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.
The module creates a Paytrail payment for the order total in euro cents and sends the order rows with it: products after discounts and shipping, 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 or Swedish when the locale of the store view is, otherwise English. The Paytrail reference is the internal ID of the Magento order.
The customer is sent to the Paytrail payment page, chooses a payment method enabled for your Paytrail account and pays. Paytrail then reports the result twice: it sends the customer back to your store and calls the callback URL server-to-server. Each store view sends its own URLs, which look like https://your-store/wcppaytrailgateway/checkout/callback/. Both are accepted only with a valid signature made with the credentials of that payment attempt, and only with the account, stamp, transaction ID and reference of that attempt. They are handled even when Enable is No or the license is not active, and whichever store view the request arrives on. The paid amount is compared with the order. The order is marked paid only after Paytrail confirms it this way. The module handles these Paytrail statuses:
After a confirmed payment the order moves to the state set in Order status after payment, the customer sees the standard order success page and the order e-mail is queued. The cron job of the module sends it the next time the Magento cron runs. While Paytrail has not confirmed the payment, the customer sees a simple Paytrail page with Your payment is pending provider confirmation. Please check again. and a Check again link. When the payment needs your review, the page says Your payment requires store review. Please contact the store. A return in another browser shows Payment result received. Please check your order confirmation or contact the store. A return that cannot be verified shows Payment verification failed. and changes nothing.
After a cancelled or failed payment the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Paytrail payment failed or was cancelled. You may try again.
If Paytrail refuses to start the payment, the order is cancelled, the cart is restored and the customer sees Paytrail could not start the payment. Please try again or choose another payment method. The module also cancels the order and restores the cart with Paytrail is unavailable for this order. (for example, the module was disabled or the total is outside your limits), Paytrail accepts totals from 0.01 to 999999.99 EUR using two decimal places. or Paytrail is temporarily unavailable. Please try again.
If the answer of Paytrail to the start of a payment is lost or invalid (timeout, server error, invalid signature), the module cannot know whether a payment exists. The order stays in Pending Payment, no second payment is started and the customer gets the page with Your payment requires store review. Please contact the store.
A Paytrail payment cannot be cancelled through the API. While an earlier payment of the cart is pending, paid or under review, no new payment is started and the customer gets the status page instead. If the payment page is requested again while an earlier payment is merely open, a new Paytrail payment is created. If the customer also pays the older page, the second payment is reported on the order as a duplicate to refund. If the cart was already paid by an earlier order, the new order is cancelled and the customer sees Your earlier payment has already been received. Please check your order confirmation.
Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), also orders with a delayed payment. The module does not stop such a cancellation. If Paytrail later reports a payment for a cancelled order, the order is not invoiced and not reopened: it stays Canceled and a note asks you to review the payment. For payment methods with a long delay, set this lifetime accordingly.
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 capture or invoice activation and no settlement reports. Paytrail is not offered for orders created in the Admin or for checkout with multiple addresses.
Orders and refunds
Order statuses
Pending Payment: the order was placed and the customer was sent to Paytrail, but Paytrail has not confirmed the payment yet. There is no invoice. For a pending payment a note shows the transaction and the payment method used at Paytrail.
Processing or Complete: Paytrail confirmed the payment. The state follows Order status after payment. The invoice has the Paytrail transaction as its transaction ID, and a note shows the transaction, the payment method used at Paytrail, the amount and the mode.
On Hold: the paid amount differs from the order total or the order changed in the meantime; no invoice is created and a note shows the received and the expected amount. Or a test payment was received while live mode is selected: the note says TEST payment received while live mode is selected. No real money. Do not ship.
Canceled: the payment failed or was cancelled, the payment could not be started, or the order was cancelled in Magento. A payment that arrives after that creates no invoice; a note asks you to review it.
Closed: the payment was fully refunded with a credit memo.
Repeated or parallel callbacks and returns never invoice an order twice or duplicate notes. If a second attempt of an already paid cart is paid, the order is not changed; a note says Duplicate Paytrail payment with its transaction and asks you to refund it in the Paytrail Merchant Panel. The notes are order comments that the customer does not see.
Paytrail payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after a confirmed payment, Paytrail stamp, Payment mode, Paytrail transaction ID, Paytrail provider and Paid amount in cents. The customer, the e-mails and the PDFs show only the payment method title.
Below the order the section Paytrail payment history lists every payment attempt (stamp, transaction, mode, status, initialization, provider, expected and received amount) and the Refunds (stamp, amount, status, refund channel, provider status, credit memo ID, reason). It is shown also when the module is disabled.
Refunds
Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Paytrail. Full and partial refunds are supported. The Comment Text of the credit memo is kept as the reason in the refund history; it is not sent to Paytrail. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Paytrail.
The refund is made in euros, for the Grand Total of the credit memo, up to the amount Paytrail actually took minus what was already refunded (Refund exceeds the remaining verified Paytrail amount.). It uses the credentials of the mode the payment was made in. Refunds are available once Paytrail has confirmed the payment and the order has an invoice. A full refund closes the order.
If the payment method does not support direct refunds, the module starts an e-mail refund automatically: Paytrail e-mails the customer at the address of the order to ask for a bank account. A note says so, and the refund history shows the channel.
If Paytrail rejects the refund, Magento shows Paytrail rejected the refund. No native credit memo was saved. or Paytrail reported a failed refund. No credit memo was saved. and the credit memo is not created. A refund can be completed at once or later: Paytrail's later confirmation is added as a note. If Paytrail reports later that it could not complete the refund, the credit memo stays on record, and a note says that the money was not returned: refund the customer another way and correct the accounting. Further online refunds of that payment are then blocked.
Every refund request is recorded before it is sent. If the answer of Paytrail is lost or invalid, Magento shows The refund result is uncertain. Check Paytrail before retrying. and no further online refund is sent for that payment. Check the refund in the Paytrail Merchant Panel. If Paytrail accepted a refund but Magento could not save the credit memo, retrying the same amount saves the credit memo without a second refund at Paytrail.
Refunds made in the Paytrail Merchant Panel are not synchronized back to Magento. Create a credit memo with Refund Offline to record them.
Payments held for review
A payment that creates no invoice (a different amount, or a payment after cancellation) can be refunded in the Paytrail payment history section with Refund held payment: enter the Amount (EUR), up to what Paytrail took, and optionally a Reason. The form is shown to Admin users whose role allows credit memos. No invoice or credit memo is created; a note records the refund. Duplicate payments are refunded in the Paytrail Merchant Panel.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paytrail Gateway is the first row of the VibeFox Paytrail Gateway group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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: magento-payment-paytrail and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.
One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.
Troubleshooting
Paytrail does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that either Test mode is Yes or Merchant ID and Secret key are set (not the public test account 375917). Check that the cart currency is EUR. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total; a maximum of 0.00 hides the method, so leave the field empty for no limit.
The payment went through, but the order stays Pending Payment: the callback cannot reach your store, and the customer did not come back to it, or the signature could not be checked. The callback URL must be reachable from the internet (no basic authentication or firewall in the way). Check that the Merchant ID and Secret key of the mode the payment was made in are correct. A pending or delayed payment waits until Paytrail confirms it. Look at the Log field for the reason.
Callback or return answers Payment verification failed.: the signature is invalid, or the payment does not belong to a payment attempt of this store. Nothing is changed. Check that the Secret key is correct and belongs to the Merchant ID.
The callback answers Please retry.: the order was being confirmed by another request at the same moment, or an error occurred while the order was being updated. Nothing was changed by this request, and the next callback or return confirms the order. Look at the Log field for the reason. The customer sees Payment confirmation is busy. Please check again. in the same situation.
Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback and return URLs too. The order is confirmed by the next callback or return that reaches the store.
The order e-mail is not sent after payment: check that the Magento cron runs and that order e-mails are enabled in Stores > Configuration > Sales > Sales Emails.
The customer is back in the cart with Paytrail could not start the payment: look at the Log field. For example, API error 401 means wrong credentials. The order of that attempt is cancelled.
The merchant ID is not saved: it must contain digits only. Copy it again from the Paytrail Merchant Panel.
The order is On Hold or a note asks for review: read the note on the order and the Paytrail payment history section. The reason is a different paid amount, a changed order, a payment after cancellation or a test payment in live mode. Check the payment in the Paytrail Merchant Panel, then fulfil the order or refund the payment with Refund held payment. A test payment moved no money.
The refund says An earlier refund has an uncertain result: an earlier request has no clear answer, for example after a timeout. No further online refund is sent for this payment. Check the Paytrail Merchant Panel, make any missing refund there and record it with Refund Offline.
The refund says The Paytrail credentials of this payment mode are missing: the payment was made in live mode, and the Merchant ID or Secret key is empty now. Nothing was sent to Paytrail and no credit memo was saved. Enter them and create the credit memo again.
The refund says A native Paytrail invoice is required for an online credit memo.: start the credit memo from the invoice (Invoices tab). An order without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; use Refund held payment. The message also appears when the private journals were deleted by an uninstall with data removal.
The refund says An accepted Paytrail refund awaits its native credit memo. Retry the same amount first.: Paytrail accepted an earlier refund, but Magento did not save its credit memo. Create the credit memo again with the same amount; no second refund is sent.
The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Developer event: the ptg_payment_request event can change the additional data of the payment request before it is signed and sent. The stamp, reference, amount, currency and the return and callback URLs are restored after the event, and the rows must still add up to the order total.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PaytrailPayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PaytrailPayment to remove the data, then bin/magento module:disable Vibefox_PaytrailPayment, delete the folder app/code/Vibefox/PaytrailPayment and run bin/magento setup:upgrade.
The license key and license status are always removed. If Delete module data on uninstall is No, the settings and the private journals of payment attempts and refunds are kept for a re-install, so orders paid before can still be refunded. If it is Yes, the module settings of all scopes, these journals, the module cache and the log are removed. This cannot be undone: old payments can then be refunded only in the Paytrail Merchant Panel. Existing orders always keep their invoices, credit memos, payment notes and transaction IDs.
Paytrail is a trademark of its respective owner. This module is not affiliated with or endorsed by Paytrail.