VibeFox Tpay for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions. The OpenSSL extension and outgoing HTTPS to secure.tpay.com are needed for the JWS signature check of notifications.

Shop currency: Polish złoty (PLN) only. Tpay settles in PLN and its Open API has no currency field, so the payment method is hidden when the cart uses another currency.

Internet access to your shop: Tpay sends payment notifications to your shop, so the notification address must be reachable from the internet (not blocked by a firewall or HTTP authentication).

Tpay account: you need these values from the Tpay merchant panel: the Merchant ID (your Tpay account ID), the Open API keys Client ID and Client secret (Integration, API) and the security code (Settings, Notifications). Sandbox keys come from a separate Tpay sandbox account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Tpay Payment in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the Sandbox keys and the Production keys (see Configuration). Nothing has to be set in the Tpay panel except the security code: the notification address is sent with every transaction.

5. Turn on Enable/Disable and click Save. Test a payment in sandbox mode, then turn off Sandbox mode to accept real payments.

On install the module creates the order status Tpay payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; PLN must stay allowed for the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Tpay Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. while sandbox mode is on. It warns you when the keys of the current mode are incomplete (Tpay is then not shown at checkout), when the shop's default currency is not PLN, and when the OpenSSL PHP extension is missing while the JWS check is on (payments would then not be confirmed). Spaces pasted with the Merchant ID or Client ID are removed when you save.

Tpay

Enable/Disable: Enable Tpay payments turns the payment method on or off. Default: off.

Title: the payment method title displayed to customers at checkout. It is also the payment method name stored in the order. Default: Tpay. Required.

Description: the payment method description displayed to customers at checkout. Default: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: uses the Tpay sandbox (test payments, no real money) with the Sandbox keys and openapi.sandbox.tpay.com. Turn it off to accept real payments with the Production keys. Refunds always go to the environment in which the order was paid. Default: on.

Production keys

Where to find them: in the Tpay merchant panel under Integration, API (Open API keys: Client ID and Secret); the Merchant ID is your Tpay account ID; the security code is in Settings, Notifications.

Merchant ID: your Tpay account ID (digits). Tpay sends it in every notification.

Client ID: the Open API Client ID.

Client secret: the Open API Client secret.

Security code: used to verify the MD5 checksum of Tpay notifications.

Sandbox keys

The sandbox is a separate Tpay test account with its own keys (see the Tpay API documentation). Used only while Sandbox mode is on.

Sandbox Merchant ID: the Merchant ID of the sandbox account.

Sandbox Client ID: the Open API Client ID of the sandbox account.

Sandbox Client secret: the Open API Client secret of the sandbox account.

Sandbox Security code: the notification security code of the sandbox account.

Saved secrets (Client secret and Security code of both environments) are never shown again. The field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a secret and click Save to remove it. An empty field keeps the saved value.

Payment notifications

Notification URL: Tpay confirms payments to the address shown here. With friendly URLs it looks like https://your-shop/module/wcp_tpay_payment/notify, possibly with a language code such as /en/. The address is sent with every transaction automatically; nothing has to be set in the Tpay panel except the security code. An order is created only after a notification with a valid checksum and signature and a matching amount (or a matching status check when the customer returns). Tpay repeats a notification until your shop accepts it.

JWS signature: also verifies the X-JWS-Signature of notifications with the Tpay certificate (recommended). Requires the OpenSSL PHP extension and outgoing HTTPS to secure.tpay.com. The certificates are cached for a day. The MD5 checksum is always verified. Default: on.

Advanced

Debug log: logs payment events: technical events only (no keys, no customer data) in logs/wc_tp_debug.log.php in the module folder. The file cannot be opened from the web. Default: off. Nothing is written while it is off, errors included, so turn it on before you look for the cause of a problem.

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 module removes the module settings and the log. Orders and their Tpay payment data are always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Tpay). In sandbox mode the payment option shows Sandbox mode - no real money is charged. After confirming, the module creates a Tpay transaction for the cart total in PLN with the description Cart # and the cart number, passes the customer's name, e-mail, invoice address and phone, and sends the customer to the Tpay payment page. The page is shown in Polish, English or Ukrainian, following the shop language (other languages get English). There the customer chooses BLIK, a bank transfer, a card or another method enabled on your Tpay account and pays. No order exists yet at this point.

The order is marked paid only after Tpay confirms it. Tpay sends a notification to your shop; the module checks the MD5 checksum with the security code, the Merchant ID and (when on) the JWS signature, using the keys of the environment the payment was started in, and then the amount: it must equal the amount requested for this payment attempt and the cart total, and the paid amount must not be lower. Notifications without a valid checksum or signature are rejected. The order is then created and the customer gets the standard order confirmation page.

After paying, the customer returns to your shop. Returning alone does not mark anything paid. If the notification has not arrived yet, the module asks the Tpay API for the status of the transaction (at most every 10 seconds) and applies the same checks. While the payment is not confirmed, a Payment confirmation page shows Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: with a Refresh button and a Pay again button that leads back to checkout. The notification creates the order as soon as it arrives.

If Tpay reports that the payment failed, the customer is back at checkout with Tpay reports that the payment did not go through. Please try again or choose another payment method. If the payment fails on the Tpay page, Tpay sends the customer back to the checkout page. The cart is kept in both cases. If the order went on hold, the confirmation page shows Your payment is being verified. We will contact you as soon as it is confirmed.

Each payment attempt has its own reference. When the customer pays again, the earlier unpaid Tpay transactions of the cart are cancelled at Tpay; a payment that already went through on an earlier link is still accepted. If the cart already has an order, the customer goes to its confirmation page instead of a new payment.

If Tpay cannot start the payment, the customer stays at checkout with The Tpay payment could not be started. Please try again or choose another payment method. and the reason goes to the log (when Debug log is on).

The notification address works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module works in PLN only. There is no bank or BLIK code selection in the shop (the customer chooses on the Tpay page), no saved cards, no subscriptions, no Apple Pay or Google Pay buttons in the shop and no installment calculators.

Orders and refunds

Order statuses

No order yet: the customer was sent to Tpay and has not paid, or Tpay has not confirmed the payment yet. Only the cart exists. A failed payment creates no order either.

Payment accepted: Tpay confirmed the payment. The payment is recorded with the Tpay transaction title (TR-...) as the transaction ID. A note says whether it was confirmed by the notification or by the status check, the environment, and any overpayment.

Tpay payment on hold: a payment arrived, but its amount differed from the requested amount or the cart total (for example, the cart was changed after the payment started), only part was paid, or the payment arrived after the order had been cancelled. The note explains it. Check the payment in the Tpay panel and fulfil or refund the order. If the customer then pays the correct amount through a new attempt, the order moves to Payment accepted.

Refunded: the payment was fully refunded through the module.

If Tpay reports another payment for an order that is already paid or refunded, the order is not changed; a note asks you to refund the extra payment in the Tpay panel if needed. A chargeback reported by Tpay adds a note.

Tpay payment block

The order page shows a Tpay payment block with the Tpay transaction title and ID, the payment reference (CRC), the environment (with a Sandbox badge for sandbox payments), the payment status and how it was confirmed, the paid amount, the order total and the amount refunded, the refund history, all Payment attempts of the cart and the Payment notes of the order.

Refunds

In the Tpay payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Tpay. Confirm the question Refund this amount through Tpay? This cannot be undone. Full and partial refunds are supported for orders with a payment received through Tpay, including orders on hold. You need the right to edit orders; access to the Modules pages is not needed. You can refund up to the amount the paying Tpay transaction took, at most the order total: after a partial payment or a changed cart the block shows Refundable (paid through Tpay). The refund is sent to the environment (sandbox or production) where the order was paid, so the keys of that environment must be set. The refund counts as done only when Tpay confirms it; a refund rejected or not confirmed by Tpay is shown as an error and not recorded. A successful refund is added to the refund history and the notes, together with the reason you entered (the reason is not sent to Tpay). Refunding the whole refundable amount sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Tpay. Refunds made in the Tpay merchant panel are not added to PrestaShop automatically.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tpay Payment is the first block on Modules > Module Manager > VibeFox Tpay Payment > Configure, 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 shop. Below them are the line Product: presta-payment-tpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Tpay 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Tpay does not appear at checkout: check that the license is active, Enable/Disable is on and all four keys of the current mode are entered (Merchant ID, Client ID, Client secret, Security code). Check that the cart currency is PLN and that the module is allowed for PLN, the customer's country and the customer's group in Payment > Preferences. The settings page shows a warning for missing keys and a non-PLN shop currency.

The payment went through, but no order was created: Tpay could not deliver the notification or it was rejected. Turn on Debug log and look at the Log field on the module page. The usual causes are a wrong security code or Merchant ID for the environment of the payment, a blocked notification address (firewall, HTTP authentication), or a server without OpenSSL or outgoing HTTPS for the JWS check. The order is also created when the customer returns to the shop after paying.

Notification answered FALSE - invalid checksum: the Merchant ID or security code in the settings does not match the Tpay account (sandbox or production) of the payment.

Notification answered FALSE - invalid JWS signature: the signature could not be verified, for example because OpenSSL is missing or the Tpay certificate cannot be downloaded. Fix the server or, if needed, turn off JWS signature; the MD5 checksum is still checked.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: the cart was being processed by another request at the same moment, or the order could not be created (for example, the module is disabled). Tpay repeats the notification automatically. Turn on Debug log to see the reason.

The notification URL shows FALSE - POST only in the browser: this is normal. The URL accepts only notifications from Tpay.

The order is Tpay payment on hold: read the notes in the Tpay payment block (see Order statuses), check the payment in the Tpay panel, then fulfil the order or refund the payment.

The customer saw The Tpay payment could not be started: the keys of the current mode are wrong or Tpay rejected the request. Turn on Debug log; the log shows the Tpay error.

The customer saw We could not match this payment to an order: the return link did not belong to the customer's cart. If the customer was charged, the notification still creates the order; check the Tpay panel.

Refund fails: if the message says the keys are missing, enter the keys of the environment where the order was paid. If the message says the amount is too high, at most the shown amount can be refunded. If Tpay did not confirm the refund, check the transaction in the Tpay merchant panel before trying again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Tpay Payment and choose Uninstall. The license key and license status of this module are always removed. The cached Tpay access tokens and certificates are always removed. If Delete data on uninstall is on, the module settings and the log are removed too. If it is off, the settings are kept for a later re-install. The Tpay transactions and refunds and the order status Tpay payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

Tpay is a trademark of its respective owner. This module is not affiliated with or endorsed by Tpay.