Tpay and WooCommerce: integration and setup step by step
Tpay for WooCommerce, set up step by step: Open API keys, the security code, the sandbox, common errors and fees. Check it before you switch payments on.
The Tpay WooCommerce integration connects a shop to a Polish payment gateway: the customer pays with BLIK (the Polish mobile payment system), a bank transfer, a card or Google Pay, and the order status updates automatically once the payment is booked.
How the Tpay WooCommerce integration works
Image generated by AI
The Tpay WooCommerce integration lets you take payments directly in the shop and update orders automatically. It runs on the official plugin from the operator of Tpay, the Poznań company Krajowy Integrator Płatności.
Once the gateway is live you can offer customers BLIK, fast bank transfers, cards and Google Pay. Depending on your agreement with Tpay, instalments and BLIK Płacę Później (BLIK’s buy now, pay later option) may also be available.
A big advantage of the integration is the way payments are presented in the checkout. The customer can type the BLIK code directly in the shop. With fast transfers they see bank tiles and pick their bank straight away. Every extra step makes the purchase longer, so this kind of simplification matters most on a phone.
When the payment is finished, Tpay sends a notification to WooCommerce. The shop receives it and changes the order status, for example from “Pending payment” to “Processing”. There is no need to check every payment by hand in the operator’s panel.
From the Tpay panel you can also issue full and partial refunds. That is useful when a customer returns one product from a larger order or gets part of the cost back.
Before you start: a Tpay account and Open API keys
Image generated by AI
To switch the gateway on you need a verified Tpay account and three details: the Client ID, the Secret and the security code. The shop itself should already have a working basket, checkout and the basic sales documents.
During verification Tpay may check the company details, the shop’s terms and conditions, the privacy policy and the information about the seller. Go through the full purchase path beforehand. Add a product to the basket, enter customer details and check that you can get as far as choosing a payment method. If you are only just building the shop, go through my guide on how to start an online store on WordPress first.
You will find the Client ID and the Secret in Panel Sprzedawcy. Go to the “Integracja” (Integration) section, open the “API” tab and find the item “Klucze do nowego Open API” (Keys for the new Open API). The security code is in the notification settings. The full description of the setup is in the Tpay plugin implementation documentation.
The details you need are:
- the Client ID, used when connecting the shop to the Tpay API,
- the Secret, which confirms the shop’s permissions,
- the security code, used to verify transaction notifications.
Treat the Client Secret like a password. Keep it out of public documents, messages sent to random people and screenshots of the shop’s back office.
The Merchant ID is the login to Panel Sprzedawcy. The standard payment setup is based on the Open API details, but the Merchant ID may also be required when switching on instalments.
In the Tpay panel switch on the “Zezwól na nadpisanie adresu URL powiadomienia” permission. The plugin then passes the right address, the one the operator sends payment information to. With the permission off, the customer can pay correctly and the order will still be waiting for payment.
The Tpay plugin supports shops that sell in Polish zloty. If WooCommerce uses a different currency, or a currency converter changes the order currency, the gateway will not handle that transaction.
Setting up Tpay in WooCommerce step by step
The setup consists of installing the official plugin, entering the keys and switching on the payment methods you want. At the end, place a test order and check the whole path, including the status change.
Step 1. Download and install the official Tpay plugin
You can download the Open API version of the plugin from the Tpay shop modules page. The latest releases are also published in Tpay’s GitHub repositories. You need the ZIP package to install it.
In the WordPress admin go to “Plugins”, choose “Add new” and then “Upload plugin”. Select the downloaded ZIP file, start the installation and activate the module.
Newer versions support HPOS, a more efficient way of storing orders in WooCommerce, and the block-based checkout. The plugin itself being compatible does not rule out a conflict with the theme, a shipping module or an add-on that changes the order fields.
Make a backup before installing. Check the versions of WordPress, WooCommerce, PHP and the theme you use as well. Updates are best done beforehand on a copy of the shop, especially when sales are already running.
Step 2. Enter the Client ID, the Secret and the security code
You enter the access details in the global Tpay settings in WooCommerce. In the same place you choose the production or the test environment.
Production uses details created in panel.tpay.com. The sandbox has its own panel at panel.sandbox.tpay.com and a separate set of keys. The Client ID, the Secret and the security code have to come from one environment.
Combining a production Client ID with a test Secret ends in an authentication error. A space picked up while copying can have a similar effect. The safest thing is to paste all the values in again, without typing them by hand.
After saving the settings, check whether the plugin reports a correct connection. If you see an error, start with the environment and the keys. Only then move on to looking at the firewall or the server configuration.
Step 3. Switch on the payment methods in the checkout
The methods Tpay supports appear as separate items in the WooCommerce payment settings. To begin with, BLIK, fast transfers and cards are usually enough. You can switch on Google Pay and instalments once they have been activated on your Tpay account.
BLIK with the code typed in the shop deserves a high place on the list. The customer enters six digits, confirms the payment in their banking app and often finishes the whole process in under twenty seconds.
After setting the order of the methods, open the checkout on a phone. Check that the names are readable, the bank tiles fit on the screen and the payment fields do not overlap the order summary.
The plugin also lets you tie payment methods to chosen delivery methods. For example, you can show a particular option only with courier shipping. Test rules like that for every delivery method available.
The Tpay module can cancel unpaid orders automatically after a set number of days, 30 at most. WooCommerce also has its own setting for how long stock is held. The default is usually 60 minutes, after which an unpaid order may be cancelled. Set both mechanisms deliberately, so that products do not go back into stock too early.
Step 4. Place a test order and check the status change
The test should cover the customer’s full path: adding a product to the basket, the checkout, choosing Tpay, the payment and the return to the shop. After a correct transaction the order status should change from “Pending payment” to “Processing”.
Check these as well:
- the emails sent to the customer and to the shop staff,
- the stock level going down,
- the transaction record in the Tpay panel,
- that the amount, the currency and the order number match,
- how the shop behaves after the thank-you page is refreshed.
The payment confirmation screen alone tells you too little. What matters most is the notification Tpay sends to the shop, because WooCommerce updates the order on the basis of it.
The Tpay sandbox and going to production
The sandbox lets you check the integration without making real payments. It has its own panel, account and keys, so going to production means replacing the whole set of details.
Run several scenarios in the test environment. Start with a successful payment, then cancel a transaction before paying and go back to the shop without finishing it. Check a full refund and a partial refund issued from the Tpay panel too.
Watch the order statuses after every test. A paid order should move to processing, and an interrupted payment should stay unpaid. A refund has to carry the right amount and refer to the right transaction.
When testing is finished, choose the production environment and enter the Client ID, the Secret and the security code from the production panel. Clear the cache of the site, the server and the CDN if you use one. Then open the checkout in a private browser window to see the version without saved data and old cache.
Place the first production order for a small amount and pay for it with a real method. Check the Tpay panel, WooCommerce, the emails and the stock level. This way you catch problems before a customer runs into them.
Common integration errors and how to fix them
Most problems with the Tpay WooCommerce integration come from mixed-up keys, blocked notifications or an unsupported currency. Start with these three points, because they usually lead to the cause quickly.
An authentication error most often means details taken from two panels. Copy the whole set again from production or from the sandbox. Remove any stray spaces before and after each value.
When the customer has paid and the order still has the “Pending payment” status, check the permission to override the notification URL. Then exclude the addresses that handle Tpay notifications from the cache. Look at the firewall settings and the hosting’s security features too, as they can reject incoming connections.
Currency problems often appear after a currency converter is installed. The product may be shown to the customer in euros, while Tpay in this integration handles payments in PLN. Check the currency saved on the order itself.
Diagnose plugin conflicts on a copy of the shop. Switch add-ons off one at a time and create a new order after each change. An old order may keep data saved by the earlier configuration.
In the WooCommerce logs look for connection errors, API responses and information about status changes. The notification history in the Tpay panel shows whether the operator sent the message and how the shop replied. Comparing the two records usually shows the moment at which the process broke.
Tpay fees in practice
Tpay fees depend on the variant you choose and the type of payment. The two main plans are Starter, billed with no monthly subscription, and Business with a fee of PLN 99 a month.
On the Starter plan activation costs PLN 99. Transfers, cards and digital wallets are charged at 1.59% + PLN 0.39 per transaction, and BLIK at 1.59% + PLN 0.41. A refund costs PLN 1, except for card refunds, and a payout costs PLN 2.
Business has activation for PLN 1 and a subscription of PLN 99 a month. The fee is 0.99% with no standard fixed charge, although PLN 0.02 is added for BLIK. Refunds and payouts are free.
For an order of PLN 100 the payment cost on Starter comes to about PLN 1.98 for a transfer or a card and about PLN 2 for BLIK. That is roughly 2% of the basket value.
With a basket of PLN 40 the fixed charge takes a bigger share. The fee for a transfer or a card comes to about PLN 1.03, or about 2.6% of the order. A shop with cheaper products will feel the difference between the price lists sooner.
With an average basket of around PLN 100 the two variants come close in cost at a monthly turnover of about PLN 10,000. A lower order value can move the line in favour of the Business plan.
Tpay pays out on a D+1 basis. With higher turnover you may get an individual offer. Before signing the agreement, check the current Tpay price list, the payout rules and the rates assigned to specific methods, because commercial terms can change. Fees are only one item in a shop’s budget. You will find the full breakdown in the article how much does an online store cost.
Tpay, Przelewy24 or PayU: which to choose for WooCommerce
Tpay, Przelewy24 and PayU all handle BLIK, fast transfers and cards. Base the decision on the costs for your basket, how easy the implementation is, the payout times and the reports your accountant uses.
The Przelewy24 plugin is downloaded from the operator’s site. The PayU module is available in the WordPress directory, and the Tpay plugin on the operator’s modules page and in its GitHub repositories. I have described both competing implementations step by step in my guides to the Przelewy24 integration with WooCommerce and the PayU integration with WooCommerce.
Each gateway needs a different set of details. Przelewy24 uses a merchant ID, a CRC key and an API key. PayU requires four details of the REST API point of sale. With the Tpay WooCommerce integration you provide the Client ID, the Secret and the security code.
Tpay stands out for the BLIK code typed directly in the shop and the bank tiles shown in the checkout. The subscription plan can suit a shop with regular turnover well. The limitation is that it only handles orders in Polish zloty.
When comparing offers, work out the cost for your own average order value and monthly number of transactions. Add the fixed charges, the subscription, refunds and payouts. Only that calculation shows which gateway makes sense for your shop.
FAQ
How much is the Tpay fee in WooCommerce?
On the Starter plan transfers, cards and digital wallets cost 1.59% + PLN 0.39 per transaction, and BLIK 1.59% + PLN 0.41, with no subscription. The Business plan for PLN 99 a month lowers the fee to 0.99% and removes the charges for refunds and payouts. You will find individual rates in your agreement and in the panel.
What details do I need to set up the Tpay plugin?
Three values from Panel Sprzedawcy: the Client ID and the Secret from the “Integracja” section, “API” tab (the item “Klucze do nowego Open API”), and the security code from the notification settings. For instalments you also need the Merchant ID, which is the login to the panel. Switch on the permission to override the notification URL as well.
Does Tpay support BLIK without redirecting to the operator’s site?
Yes. The customer types the six-digit BLIK code directly in the shop’s checkout and confirms the payment in their banking app, without leaving the page. The whole process often takes under twenty seconds.
Why does the order not change status after being paid through Tpay?
Most often the shop is not receiving notifications. Check that the permission to override the notification URL is switched on in the Tpay panel, then the cache and the firewall: the payment notification addresses should be excluded from the cache. Compare the amount and the currency of the order with the transaction in the panel too.
Will the Tpay plugin work for a shop selling in euros?
No. The integration handles payments in Polish zloty. With multi-currency sales you can settle the PLN orders through Tpay, but for the other currencies you need a different gateway or a separate solution.