Developer Documentation

Magento 2 Payment Extension

Last Updated: June 6, 2023

Extension overview

The Truevo Magento 2 Payment Extension makes accepting ecommerce payments easy. Your customers will not only be able to make payments on your website but will also have the ability to securely save their card details for convenient repeat purchases. In addition, you will be able to perform full reversals and full or partial refunds from the Magento backend system. 

We’ve also included some important transactional information for you, meaning doing reconciliation between your Magento backend and Truevo Portal just got easier. 

Compatible with Magento 2.3.5 or higher.

Installation steps

Step 1

First you will need to download the Magento Extension Do not rename the file as this may cause issues in the future.

Step 2

Let’s be careful. Sometimes complications can arise when you install third-party extensions. So, we suggest that you make a backup of your shop. We also recommend first testing the integration on a test system, if you can.

The next steps are very technical and can be tricky. If you usually have a professional web technician configure your Magento store for you, now’s the time to hand the computer over to them.

Step 3

Create an app/code directory and set the owner to apache:apache.

Step 4

Create a Truevo/PaymentGateway directory within app/code

Step 5

Open the extracted folder and upload the Truevo folder to app/code on the FTP or if you already have the directory created you can just take the contents of the PaymentGateway folder and paste in app/code/Truevo/PaymentGateway.

Step 6

Open a terminal connection to your Magento 2 site, navigate to the root of your site and then run the following commands from the /var/www/html/magento root directory:

  • php bin/magento Extension:enable Truevo_PaymentGateway
  • php bin/magento setup:upgrade
  • php bin/magento setup:di:compile
  • php bin/magento setup:static-content:deploy-f

Step 7

Head over to your Magento Admin and log in as an Administrator. Once logged in and on the dashboard, make your way to the following directory: System > Cache Management. On the Cache management screen, in the top right corner, please click on Flush Magento Cache.


Step 1

Log in to your Magento Admin, navigate to Stores > Settings and click on Configuration. Navigate to Sales > Payment Methods and locate Truevo payment gateway services, select Configure.

Step 2

Under the Credentials section you will be asked to add your Live Merchant ID (mid), LiveTerminal ID (tid) and Live API Token. These pieces of information would have been provided to you via email. What does each of these do?

The Merchant ID is a unique number that we’ve registered with the schemes and is what is used to identify your business. Each mid is also associated with a single currency.

The Terminal ID is linked to the mid and is used to identify the source of the transaction.

The API Token is assigned to an account and makes it possible to perform transaction requests such as reversals and refunds. It also makes it possible for us to provide detailed transaction information to the WooCommerce backend, which makes reconciliation easier.

At this point, you can also enable test mode. Don’t worry, if you choose to enable test mode your Production mid, tid and API Token will save and you will not have to input them again. We recommend doing a few tests before going live. You can find testing credentials below.

Step 3

Next you will need to configure your Card Payment Options. This will involve enabling Truevo Payments, the extension will not work unless this has been enabled.

Step 4

Next you will be asked if you want to enable tokenisation. This feature allows your customers to securely save their card details, making repeat purchases easier and faster.

How does it work? If enabled, your customer will need to create a profile on your ecommerce store. When entering their card details for the first time they will need to select the checkbox that says: Save card details. When your customer returns to make another purchase they will be shown a list of card details they have previously provided and can select an existing card, or add a new one. If they select an existing card they will simply enter their security code and go through the 3D Secure v2 flow. This significantly speeds up the checkout process.

Step 5

You will now see the option to Enable Pre-Authorisation. By enabling this each payment made on your store will be a pre-authorised payment, in order to complete the transaction you will need to capture the payment. You can use the Magento backend to capture the full pre-authorised amount, however, if you would like to capture a partial pre-authorisation you will need to do this from the Truevo Portal.

Please note that this feature will only work if your account has been set up to accept pre-authorisations.

Step 6

You will then be asked to provide a Title and Description.

The Payment Method Title is what your customers will see when selecting a payment method. When choosing what to place here we suggest keeping it short, simple and clear, for example, use: Pay with a card.

The Payment Method Description provides your customers with more information about how they are paying. Here it’s a good idea to mention what types of cards they can use, for example: Pay with a Visa, Mastercard or Maestro debit or credit card.

Step 7

You will also be asked if you want to show the Truevo seal of trust at the bottom of your payment form, please note that if you uncheck this it will continue to show - we are working on a fix for this.

In addition, the Widget Theme is currently only available as a card theme, a plain theme will be released at a later date.

Step 8

When designing the Truevo payment form we went for a very minimalistic design, with the aim of making it look like it belongs on your website. If you would like to personalise your form you are welcome to do so by adding some custom CSS. Please note that this will only let you make adjustments to the colour, font and general styling, you will not be able to change the placement of the form or the payment flow. For more information on how to customise your form with CSS please review our styling capabilities documentation.

Step 9

And last but not least, save. If you close this configuration page without saving, all of your settings will be deleted and you will need to redo the configuration.

Test integration credentials

Please note that test credentials will not work in a live environment and that any transactions done in the test environment will not show up in your Truevo Portal. The credentials you use will also need to be in the same currency as your online store, below we have provided test credentials for EUR, GBP and USD, however, the token will be the same for all three currencies.

Test Merchant ID (mid)
Test Terminal ID (tid)
Test Token


Test card details

Please note that test card details will only work with the test integration credentials and not with your live credentials. The test card details below will not include the 3DS flow, to test 3DS please use your live credentials and a real card.
Success Non-3DS
Card type
Mastercard Credit
Card number
Expiry date
Cardholder name
Security code

How to manage transactions from Magento 2

How to capture a payment

Need to secure payment for a future purchase but don’t want to take a deposit? Pre-authorisation is the solution for you. Using pre-authorised payments lets you hold the desired amount and only capture the payment once the product or service has been delivered, this feature is particularly useful if you are in the hospitality industry, have an appointment-based business or make products to order.

Please take note

This feature will only work if you set up pre-authorisations during your application and onboarding process. If you did not set this up and would like to please contact our support team.

Step 1

Log into your Magento Admin, from the left menu bar navigate to Sales > Orders. Locate the transaction you wish to capture and click on it, the order status should be On Hold.

Step 2

You will now be able to see all the order details and have the ability to view and edit the order. At the top navigation of the page, you will see the option to Capture Pre-Authorisation, click on it.

Step 3

The screen will refresh and a confirmation message will appear, your order status will also change to Processing.

How to perform reversals and refunds

With our new Truevo Payment Extension you are able to perform reversals and refunds from within the Magento backend. To start out, we’re going to define the difference between a reversal and a refund.

A reversal occurs when the funds from a transaction are returned to a customer before the payment has cleared. This means that the reversal request was performed the same day that the transaction took place (before 00:00 CET/CEST). For this reason, reversals are also for the full transaction amount and it will be as if the transaction never occurred, i.e. there will be no record of the transaction in your customer’s bank account.

A refund occurs when the funds from a transaction are returned to a customer after the payment has cleared. Because the transaction has been completed and the refund is a new transaction, the transaction amount can be fully or partially refunded and will show up as a separate transaction in your customer’s bank account.


Step 1

Log into your Magento Admin, from the left menu bar navigate to Sales > Orders. Locate the transaction you wish to reverse and click on it. Please note that the transaction must have happened on the same day (before 00:00 CET/CEST) for it to be classified as a reversal.

Step 2

You will now be able to see all the order details and have the ability to view and edit the order. In the top navigation of the page, you will see the option to Reverse Order, click on it.

Step 3

Once you have clicked the reverse button the page will refresh and a confirmation message will appear. Please note that you will not be asked to confirm the reversal request, so be careful to only reverse orders you are sure of. Your order status should also now say Cancelled.


Step 1

Log into your Magento Admin, from the left menu bar navigate to Sales > Orders. Locate the transaction you wish to refund and click on it. Please note that the transaction must be at least one day old before it can be classified as a refund.

Step 2

You will now be able to see all the order details and have the ability to view and edit the order. In the top navigation of the page, you will see the option to Refund Order, click on it.

Step 3

You will be redirected to a new page and will be asked how much you want to refund, how many pieces you want to refund and given the option to add reason for refund. We will automatically fill the full refund amount into the refund amount box, however, you can edit this to be any amount as long as it is equal to or less than the sale amount.

Step 4

Once you are satisfied with the information you have provided, click on Submit. You will be redirected back to the order information page and a confirmation message will display on the screen. Your order status should also now say Cancelled.

Page Contents