The Paytrail plugin adds Paytrail, a Finnish payment gateway, as a payment method at J2Commerce checkout. Customers are redirected to Paytrail to pay.
It supports saved cards, subscription renewals with a saved card, surcharges and refunds from the order screen. Paytrail accepts EUR only.
Requirements
- J2Commerce 6.3.6 or later.
- Joomla 6.0.0 or later.
- A Paytrail merchant account with a merchant ID and secret key.
- A store currency of EUR.
Installation
- Go to System -> Install -> Extensions.
- Upload the plugin package.
- Go to J2Commerce -> Payment Methods (or System -> Plugins) and open Paytrail.
- Set Status to Enabled, enter your credentials and save.
Settings
Settings are grouped in tabs.
Basic Settings
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Display Name | Name shown for the method at checkout. | Empty | Text |
| Display Image | Image shown for the method at checkout. | None | Media file |
| Test Mode | Uses your Paytrail test credentials instead of live ones. | Yes | Yes, No |
| Merchant ID | Your Paytrail merchant account ID. Shown when Test Mode is No. | Empty | Text |
| Secret Key | Your Paytrail HMAC secret key. Shown when Test Mode is No. | Empty | Text |
| Test Merchant ID | Your own Paytrail test merchant ID. Shown when Test Mode is Yes. | Empty | Text |
| Test Secret Key | Your own Paytrail test secret key. Shown when Test Mode is Yes. | Empty | Text |
| HMAC Algorithm | Signature algorithm for requests. SHA-512 is recommended. | SHA-512 | SHA-512, SHA-256 |
| Language Override | Sets the language of the Paytrail payment page. Auto uses the browser locale. | Auto (browser locale) | Auto (browser locale), Finnish, Swedish, English |
| Thank You Message Article | Article shown after a successful payment. | None | Joomla article |
| Cancel Message Article | Article shown when the customer cancels the payment. | None | Joomla article |
Saved Cards
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Enable Saved Cards | Lets customers save a card for future purchases and subscription renewals. | No | Yes, No |
| Payment Groups | Limits the Paytrail payment methods shown. Leave empty to show all. | Empty | Credit Card, Mobile, Bank, Credit / BNPL |
Order Statuses
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Payment Order Status | Status set when payment succeeds. | Status ID 1 | Any order status |
| Pending Order Status | Status set when payment is pending or delayed. | Status ID 4 | Any order status |
| Failed Order Status | Status set when payment fails or is cancelled. | Status ID 3 | Any order status |
| Change Status on Refund | Updates the order status when a refund is issued. | No | Yes, No |
| Refund Order Status | Status set after a refund is submitted to Paytrail. Shown when Change Status on Refund is Yes. | Status ID 6 | Any order status |
Surcharge
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Surcharge Name | Label the customer sees for the fee, for example Payment fee. | Empty | Text |
| Surcharge Percent (%) | Percentage of the order total added as a surcharge. | 0 | Number, 0 or more |
| Surcharge Fixed Amount | Fixed amount added as a surcharge, in the store currency. | 0 | Number, 0 or more |
| Surcharge Tax Class | Tax profile applied to the surcharge. Leave empty for no tax. | Empty | Any tax profile |
Restrictions
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Geozone Restriction | Limits the method to customers in a geozone. | Empty | Any geozone |
| Minimum Subtotal | Smallest cart subtotal for which the method is offered. | Empty | Number |
| Maximum Subtotal | Largest cart subtotal for which the method is offered. | Empty | Number |
Advanced
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Plugin Sub-Template | Layout used for the checkout payment screens. | Empty | Available sub-templates |
| Show Dashboard Icon | Shows a Paytrail quick icon on the J2Commerce dashboard. | No | Yes, No |
| Dashboard Icon Label | Label under the quick icon. Shown when Show Dashboard Icon is Yes. | Paytrail (hint) | Text |
| Dashboard Icon Class | Icon CSS class for the quick icon. | fa-solid fa-credit-card | Text |
| On After Payment | Custom text or code run after payment. | Empty | Text area |
| Debug Mode | Logs extra Paytrail API details. Turn off in production. | No | Yes, No |
Checkout and Refunds
At checkout the customer clicks Pay with Paytrail and is redirected to Paytrail. After payment they return to the store and the order status is updated from the Order Statuses settings.
With Enable Saved Cards on, customers can pick a saved card or add a new one. To refund, open the order in the admin and use Refund Order. Choose a full or partial amount and click Process Refund. Paytrail processes refunds asynchronously.
Common Setups
- Leave Test Mode on and enter your test credentials.
- Place a test order and confirm the status changes.
- Set Test Mode to No and enter your live Merchant ID and Secret Key.
Troubleshooting
- "Paytrail only supports EUR transactions." Set the store currency to EUR.
- "Paytrail credentials are not configured." Enter the Merchant ID and Secret Key for the active mode (live or test).
- "Refund amount exceeds the available refundable total." Enter an amount no higher than the maximum shown.
- Install is refused. Update J2Commerce to 6.3.6 or later.
Uninstalling
- Go to System -> Manage -> Extensions.
- Search for Paytrail, select the plugin and click Uninstall.
