VibeFox Tpay for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

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

Store 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 store (or the order being paid) uses another currency.

Internet access to your site: Tpay sends payment notifications to your store, so the notification address must be reachable from the internet (not blocked by maintenance mode, 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_tpay_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Tpay > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. 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.

6. Turn on Enable/Disable, test a payment in sandbox mode, then untick Sandbox mode to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Tpay. 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 store currency is not PLN, and when the OpenSSL PHP extension is missing while the JWS check is on (payments would then not be confirmed). In the list of payment methods, Tpay is marked as needing setup until the keys of the current mode are entered. Spaces pasted with the Merchant ID or Client ID are removed when you save.

General

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

Title: the payment method title displayed to customers at checkout. Default: Tpay.

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: Use the Tpay sandbox (test payments, no real money). Sandbox mode uses the Sandbox keys and the Tpay sandbox API. 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.

Payment notifications

Tpay confirms payments to the address shown in this section. It looks like https://your-site/wc-api/wc_tp_payment/. The address is sent with every transaction automatically; nothing has to be set in the Tpay panel except the security code. An order becomes paid only after a notification with a valid checksum and signature and a matching amount. Tpay repeats a notification until your store accepts it.

JWS signature: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Requires the OpenSSL PHP extension and outgoing HTTPS to secure.tpay.com. The MD5 checksum is always verified. Default: on.

Advanced

Debug log: Log payment events. Technical events only (no keys, no customer data) in WooCommerce > Status > Logs, source wcp_tpay_payment. Default: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Deactivation never removes anything. Orders and their Tpay payment data are always kept. Default: off.

Settings of version 1.0 are moved over automatically: keys used with test mode on become the Sandbox keys.

Checkout

The customer chooses the payment method (by default Tpay) and places the order. In sandbox mode the checkout shows Sandbox mode — no real money is charged. The plugin creates a Tpay transaction for the order total in PLN with the description Order # and the order number, passes the customer's name, e-mail, address and phone, and redirects the customer to the Tpay payment page. The page is shown in Polish, English or Ukrainian, following the site 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.

The order is marked paid only after Tpay confirms it. Tpay sends a notification to your store; the plugin checks the MD5 checksum with the security code, the Merchant ID and (when on) the JWS signature, and then the amount: it must equal the amount requested for this payment attempt and the order total, and the paid amount must not be lower. Notifications without a valid checksum or signature are rejected.

After paying, the customer returns to the order received page. Returning alone does not mark the order paid. If the notification has not arrived yet, the page 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, the 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 Pay again link. After Tpay reports a failed payment, the page shows Tpay reports that the payment did not go through. You can try again: with the same link. If the payment fails on the Tpay page, Tpay sends the customer back to the Pay for order page of the same order.

Each payment attempt has its own reference. When the customer pays again, the earlier unpaid Tpay transactions of the order are cancelled at Tpay; a payment that already went through on an earlier link is still accepted. The same cancellation happens when an unpaid order is cancelled, for example by the WooCommerce hold-stock timeout.

If Tpay cannot start the payment, the customer sees The Tpay payment could not be started. Please try again or choose another payment method. and the reason goes to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

Pending payment: the Tpay transaction was created and the payment is not confirmed yet. The order note shows the Tpay transaction and the environment.

Processing: Tpay confirmed the payment. This is the standard WooCommerce status after payment (orders with only virtual downloadable products become Completed). The note says whether it was confirmed by the notification or by the status check and shows any overpayment. The transaction ID is the Tpay transaction title (TR-...).

On hold: a payment arrived, but its amount differed from the requested amount or the order total, only part was paid, or the order had been cancelled. The order note explains it. Check the payment in the Tpay panel and complete or refund the order.

Failed: Tpay reported that the payment failed. Only a pending order is marked Failed. The customer can pay again.

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.

Refunds

Open the order, click Refund, enter the amount and click Refund via Tpay (the button shows your Title). Full and partial refunds are supported for orders with a payment received through Tpay; for unpaid orders the button is not shown. 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 in WooCommerce. A successful refund is added to the order notes, together with the reason you entered (the reason is not sent to Tpay).

Refunds made in the Tpay merchant panel are not added to WooCommerce automatically.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Tpay. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency (or the order currency on the Pay for order page) is PLN. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: Tpay could not deliver the notification or it was rejected. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_tpay_payment. The usual causes are a wrong security code or Merchant ID for the current mode, a blocked notification address (maintenance mode, firewall, HTTP authentication), or a server without OpenSSL or outgoing HTTPS for the JWS check. The order received page also checks the status when the customer returns.

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.

The order is On hold: read the order note. The paid amount did not match the order, or the payment arrived for a cancelled order. Check the payment in the Tpay panel and complete or refund the order.

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

Refund fails: if the message says the keys are missing, enter the keys of the environment where the order was paid. If Tpay did not confirm the refund, check the transaction in the Tpay merchant panel before trying again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, and so are the cached Tpay access tokens and certificates. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, Tpay transaction data and transaction IDs.

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