VibeFox Tpay for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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

Currency: Polish złoty (PLN) only. Tpay settles in PLN and its Open API has no currency field. Add PLN in System > Localisation > Currencies if your store does not have it: Tpay is shown only when the customer pays in PLN.

Internet access to your store: Tpay sends payment notifications to your store, 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_tpay_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_tpay_payment.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_tpay_payment-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Tpay Payment and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_tpay_payment.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Tpay Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Tpay keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Payment notifications).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Tpay Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 default currency of the store is not PLN (Tpay is then shown only when the customer pays in PLN), and when the OpenSSL PHP extension is missing while the JWS check is on (payments would then not be confirmed). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty or longer than 128 characters, Sort Order must be a whole number (negative values are allowed), Total must be a number, 0 or greater, and the order statuses must exist; otherwise nothing is saved. Missing keys do not block saving. Spaces pasted with the Merchant ID or Client ID are removed, and secrets are trimmed.

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, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. 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.

Sort Order: the position of Tpay among the payment methods at checkout. Leave it empty or enter a whole number (negative values are allowed).

Geo Zone: offer Tpay only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Tpay is offered. Leave it empty to offer Tpay for any total.

Production keys

Where to find them: in the Tpay merchant panel (the section links to it) 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 (the section links to 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. To remove a saved secret, tick Clear the saved value under the field and click Save.

Payment notifications

Notification URL: Tpay confirms payments to the address shown here. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_tpay_payment/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_tpay_payment/payment/wcp_tpay_payment.notify. It is built from the storefront address of your OpenCart installation. The address is sent with every transaction automatically; nothing has to be set in the Tpay panel except the security code. An order gets its status 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 store accepts it. Maintenance mode does not block the address (on OpenCart 4 the extension adds a startup action for the notifications and the return of the customer).

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.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Tpay has confirmed the payment (notification or status check). Each field below lists your OpenCart order statuses.

Paid Order Status: the status after a confirmed payment. Default: Processing.

On Hold (Review) Status: the payment needs your review (see Order statuses). Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: the extension never sets this status. A payment for an order in this status puts the order on review instead of silently reopening it. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug log: logs payment events: technical events only (no keys, no customer data) in wc_tp_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to an old copy. 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 extension removes the gateway settings and the log. Orders and their Tpay payment data are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The Client secrets and Security codes are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved Client secrets and Security codes are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Tpay). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure Tpay page to complete the payment. In sandbox mode it also shows Sandbox mode - no real money is charged. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

When the customer clicks Confirm Order, the extension 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, payment address and phone, and sends the customer to the Tpay payment page. The page is shown in Polish, English or Ukrainian, following the language of the order (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 extension 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 order total, and the paid amount must not be lower. Notifications without a valid checksum or signature are rejected. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update.

After paying, the customer returns to your store. Returning alone does not mark anything paid. If the notification has not arrived yet, the extension asks the Tpay API for the status of the transaction (at most every 10 seconds) and applies the same checks. When the payment is confirmed, the customer sees the OpenCart order success page. While it 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 sets the order status as soon as it arrives. If the order went on review, the success page also shows Your payment is being verified. We will contact you as soon as it is confirmed.

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.

OpenCart 3 creates a new order every time the Confirm Order step is shown. OpenCart 4 keeps one order for the checkout and updates it, so Pay again starts a new attempt of the same order. Each payment attempt has its own reference. When the customer pays again, the earlier unpaid Tpay transactions of the order and of other orders of the same cart are cancelled at Tpay; a payment that already went through on an earlier link is still accepted. If another order of the same cart is already paid, the customer goes to the success page instead of a new payment.

On OpenCart 4, if the order of the checkout was closed by the store meanwhile, or is already paid but the cart has changed since, including a new quantity, the customer is sent back to the checkout with Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. For an order the store cancelled before any payment the message is Order #… was cancelled by the store before the payment was completed. No Tpay payment was received for it. Please place a new order or contact us. The next Confirm Order pays a new order. On OpenCart 4 these messages, the message about the failed payment and We could not match this payment to an order. If you were charged, please contact us. are shown above the checkout page.

If Tpay cannot start the payment, the customer stays at the Confirm Order step 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). Other messages: Tpay accepts payments in Polish złoty (PLN) only. Please choose another payment method. and The order total must be greater than zero.

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

Orders and refunds

Order statuses

No status (missing order): the customer was sent to Tpay and has not paid, or Tpay has not confirmed the payment yet. A failed payment leaves the order without a status too. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Paid Order Status (default Processing): Tpay confirmed the payment. A note shows the Tpay transaction title (TR-...), the paid amount, whether it was confirmed by the notification or by the status check, the environment, and any overpayment.

On Hold (Review) Status (default Pending): a payment arrived, but the order currency is not PLN, its amount differed from the requested amount or the order total (for example, the order was changed after the payment started), only part was paid, or the payment arrived for an order in the Cancelled Order Status. 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 another attempt, the order moves to the Paid Order Status.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

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 payment for another order of a cart that is already paid leaves that order without a status and is noted on the paid order. A failed payment for an order that already has a status, a chargeback and an unknown Tpay status only add a note.

Notes are entries in the order History that the customer does not see.

VibeFox Tpay Payment tab

In Sales > Orders open an order paid with Tpay. At the bottom of the order page, next to History and Additional, the VibeFox Tpay Payment tab shows the Tpay transaction title and the Transaction ID, the payment reference (CRC), the Environment (a Sandbox label for sandbox payments), the payment Status and how it was confirmed, the paid amount, Order total / refunded, Refundable (paid through Tpay) when it differs from the order total, the refund form, the refund history, the Payment attempts of the order (with link cancelled for cancelled links) and the Payment notes. The tab is shown to users who have access to the extension.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional, kept in the note), 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 review. You need the right to modify the extension (set in System > Users > User Groups). You can refund up to the amount the paying Tpay transaction took, at most the order total. 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 the Refunded Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

Product returns in Sales > Returns do not send money back through Tpay. Refunds made in the Tpay merchant panel are not added to OpenCart automatically.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tpay Payment is the first block on Extensions > Extensions > Payments > VibeFox Tpay Payment > Edit, 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 store. Below them are the line Product: opencart-payment-tpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer pays in PLN, that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning for missing keys and a non-PLN store currency.

The payment went through, but the order stays without a status: Tpay could not deliver the notification or it was rejected. Turn on Debug log and look at the Log field on the extension 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 also gets its status when the customer returns to the store 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 updated: the cart was being processed by another request at the same moment, or the order status could not be set. 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 in the review status: read the notes in the VibeFox Tpay Payment tab (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 This payment method is not available: the checkout session no longer matches the order, or the payment method was turned off or lost its keys meanwhile. The customer reloads the checkout.

The customer saw We could not match this payment to an order: the return link did not belong to the order. If the customer was charged, the notification still sets the order status; 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. If the tab says Tpay transaction ID not found., the order has no confirmed Tpay payment to refund.

For developers: before the Tpay transaction is created, the extension triggers the OpenCart event wc_tp_transaction_data with the transaction data, the order and the environment.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Tpay Payment. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension (on OpenCart 4 its events and its startup action) and the cached Tpay access tokens and certificates are always removed. If Delete data on uninstall is on, the other gateway settings (title, description, sandbox mode, keys, JWS signature, debug log switch) and the log are removed too. If it is off, they are kept for a later re-install. The Tpay transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Tpay Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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