VibeFox Tpay for Adobe Commerce — ヘルプ

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4. The OpenSSL extension and outgoing HTTPS to the Tpay servers 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, so the payment method is hidden at checkout when the cart currency is not PLN. The module does not convert currencies.

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. Nothing else has to be set up in the Tpay panel: the module sends its notification URL with every payment.

Reachable store: Tpay sends payment notifications to your store, so the site must be reachable from the internet, without a firewall or basic authentication in front of it.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-tpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/TpayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_TpayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Tpay Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the sandbox keys (Sandbox Merchant Id, Sandbox Client Id, Sandbox Client Secret, Sandbox Security Code), keep Sandbox mode at Yes, set Enable to Yes, click Save Config and place a test order in PLN. When everything works, enter the production keys, set Sandbox mode to No and click Save Config.

The module adds the Tpay payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the Tpay payment attempts and refunds. The notification URL is sent to Tpay with every transaction, so nothing has to be configured in the Tpay panel except the security code, which you copy from there.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Tpay Payment, in the standard Magento configuration form. The fields are one list in the order below. Title and Description can be changed for a store view, the other settings for a website, with the Scope switcher at the top of the page; a payment uses the settings of the store view where the order was placed. Delete settings on uninstall is read from the Default Config only. The license block is shown only in the Default Config. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (up to 128 characters).); a Sort order that is not a whole number (Sort order must be a whole number.); a Minimum order total or Maximum order total that is not a number of 0 or greater (Order total must be non-negative.). Write amounts with a point, for example 9.99. Spaces and line breaks copied together with the Merchant ID and Client ID from the Tpay panel are removed when you save.

Notification URL: the first row after the license block shows Notification URL: and the address that receives Tpay notifications. It looks like https://your-store/wcptpaypayment/checkout/notify/ and is built for the default store view. Each payment sends Tpay the notification URL of the store view where the order was placed, so the address does not have to be entered in the Tpay panel. It only has to be reachable from the internet. While Enable is Yes, the row also shows warnings: Tpay sandbox mode is enabled.; Tpay keys of the selected environment are incomplete. (Tpay is then not shown at checkout); Tpay requires PLN; other currencies are unavailable.; and Tpay JWS verification requires OpenSSL. when the OpenSSL PHP extension is missing while JWS signature is Yes (payments would then not be confirmed by notifications). The warnings check the values of the Default Config.

Enable: shows or hides Tpay at checkout. It is shown only when the Merchant Id, Client Id, Client Secret and Security Code of the current environment are set and the cart currency is PLN. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name shown in the order. Default: Tpay. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: uses the Tpay sandbox (openapi.sandbox.tpay.com, test payments, no real money) with the Sandbox keys. Set it to No to accept real payments on api.tpay.com with the production keys. Default: Yes. While it is on, customers see TEST MODE — no real payment. Do not ship test orders. under the payment method.

Merchant Id: your Tpay account ID (digits). Tpay sends it in every notification, and the module checks it.

Client Id: the Open API Client ID from the Tpay merchant panel (Integration, API).

Client Secret: the Open API Client secret.

Security Code: the notification security code from the Tpay panel (Settings, Notifications). It is used to verify the MD5 checksum of Tpay notifications.

Sandbox Merchant Id, Sandbox Client Id, Sandbox Client Secret, Sandbox Security Code: the same four values of your Tpay sandbox account. They are used only while Sandbox mode is Yes.

Magento stores the Client Secret and Security Code of both environments encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved secret, type a new value to change it. To delete a saved secret, clear the field and click Save Config.

Production and sandbox keys are different. A payment started in one environment is always checked, cancelled and refunded with the keys of that environment, even after you switch Sandbox mode, so keep the keys of the old environment while its payments are still open or may be refunded.

JWS signature: also verifies the X-JWS-Signature of every notification with the Tpay certificate (recommended). The certificate must come from the Tpay domain of the payment environment. It needs the OpenSSL PHP extension and outgoing HTTPS; the certificates are cached for a day. The MD5 checksum is always verified. Default: Yes.

Debug log: writes payment events to var/log/wc_tp_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Keys, access tokens, e-mail addresses, IP addresses and card numbers are removed from the entries. Default: No. Nothing is written while it is No, errors included, so set it to Yes before you look for the cause of a problem.

Delete settings on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes and the log (see Uninstall). The Tpay payment and refund history is always kept. Default: No.

Sort order: the position among the payment methods at checkout. A whole number; a negative number is allowed.

Payment from applicable countries: All Allowed Countries offers Tpay for every country your store allows, Specific Countries only for the countries below.

Payment from specific countries: offer Tpay only for billing addresses in these countries.

Minimum order total: offer Tpay only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum order total: offer Tpay only up to this order total, in the base currency. Empty or 0 means no maximum.

Debug log (the last row): shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Tpay) and sees the description and the note You will be redirected to Tpay to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Tpay transaction for the order total in PLN, with the description Order # and the Magento order number, and passes the customer's name, e-mail, billing address, phone and IP address. Every payment attempt gets its own reference (CRC). The customer is sent to the Tpay payment page and pays there with BLIK, an online bank transfer, a card or another method enabled on your Tpay account. The Tpay page is shown in Polish, English or Ukrainian, following the locale of the store view (other languages get English). If the customer opens the payment step again for the same order, the same Tpay payment page is used.

The order is marked paid only after Tpay confirms it. Tpay sends a notification to your store. The module checks the Merchant ID and the MD5 checksum with the security code and, while JWS signature is Yes, the JWS signature, always with the keys of the environment the payment was started in. Then it checks 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. Notifications are accepted from any store view, and notifications, returns and refunds work also when Enable is No or the license is not active.

After a successful check Magento creates the invoice with the Tpay transaction title (TR-…) as the transaction ID, the order moves to Processing and the order e-mail is sent. If the same payment was already confirmed, nothing happens a second time.

After paying, the customer comes back to your store. The return link contains a random token of the payment attempt. Coming back alone never marks an order as paid. If the notification has not arrived yet, the module asks the Tpay API for the status of the transaction (at most once every 10 seconds) and applies the same checks. When the payment is confirmed, the customer sees the standard order success page.

While the payment is not confirmed, a page shows Tpay has not confirmed your payment yet, or it needs review. Check again or contact us before paying twice., the order number and the buttons Check again and Pay again. Pay again starts a new Tpay payment for the same order; the earlier unpaid Tpay transactions of the order are then cancelled at Tpay, and a payment that already went through on an earlier link is still matched to the order. The page works only in the browser session that placed the order. In another browser the customer lands in the cart; the payment is still confirmed by the notification.

If Tpay reports that the payment failed, or the customer comes back through the Tpay error link, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your Tpay payment was not completed. Please try again or choose another payment method. in the cart. If the first payment cannot be started, the customer sees Tpay payment could not be started. Check for an existing payment before retrying. (the reason goes to the log). When Tpay clearly rejected the request, or the module could not sign in to the Tpay API so the request was not sent, the order is cancelled and the cart is restored; when the answer of Tpay was lost, the order stays in Pending Payment and no new payment is started for it, so that the customer is not charged twice.

When an order is cancelled in Magento, including by the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the module also cancels its unpaid Tpay transactions at Tpay. See Order statuses for a payment that arrives after the cancellation.

The module works with the standard Magento (Luma) checkout and in PLN only. There is no bank or BLIK code selection on your checkout page (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. Tpay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Tpay, but the payment is not confirmed yet. There is no invoice.

Processing: Tpay confirmed the payment. The invoice is created with the Tpay transaction title as the transaction ID. A note says whether it was confirmed by the notification or by the status check, the paid amount, the environment and any overpayment. As usual in Magento, an order with nothing to ship becomes Complete.

On Hold: a payment arrived, but its amount differed from the requested amount or the order total, only part was paid, a refund of this payment already exists, or the order had been put on hold manually. No invoice is created. The note Tpay payment … held for review gives the reason and the paid amount. Check the payment in the Tpay panel, then refund it (see Refunds) or fulfil the order. If the customer then pays the correct amount through another attempt for this order, the hold is removed and the order is invoiced.

Canceled: the payment failed or was cancelled, or the order was cancelled in Magento or by the Pending Payment Order Lifetime. If a payment arrives later for such an order, the order is not reopened and not invoiced; a note says that the payment arrived for a cancelled order. Refund it if you do not fulfil the order.

Closed: the payment was fully refunded with a credit memo.

If Tpay reports another payment for an order or cart that is already paid, no second invoice is created; a note asks you to refund the extra payment in the Tpay panel if needed. A chargeback reported by Tpay and other Tpay statuses add a note. Repeated notifications never invoice an order twice. The notes are order comments that the customer does not see.

Tpay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, Tpay payment ID and Tpay environment. Below it, Tpay payment history lists every payment attempt of the order (CRC, Tpay ID and title, environment, status, requested and paid amount in PLN), and Tpay refund history lists the refunds. They are shown also when the module is disabled. On the storefront the customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The refund is sent to Tpay. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Tpay.

The refund is made in PLN, up to the amount Tpay took for the payment and at most the order total, minus the refunds already made through the module, and in 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. Magento then creates the credit memo with the Tpay refund request as the transaction ID, and a full refund closes the order. If Tpay rejects or does not confirm the refund, Magento shows the error and the credit memo is not created.

Every refund request is recorded before it is sent. If Tpay clearly rejects it, or the module could not sign in to the Tpay API so the request was not sent, you can try again. If the answer of Tpay is lost or unclear, the refund is marked as unconfirmed and no new online refund is sent for this payment, so a refund is never sent twice blindly: check it in the Tpay panel and, if needed, finish the refund there and record it with Refund Offline. Refunds made in the Tpay merchant panel are not added to Magento automatically. Create a credit memo with Refund Offline to record them.

Refund of a held or late payment: an order on hold or a cancelled order with a payment received through Tpay has no invoice. For such orders Tpay payment history shows the field Review refund amount (PLN) and the button Refund held Tpay payment. Enter the amount and click the button to send the refund to Tpay without an invoice or credit memo. Magento shows Tpay review refund accepted. and adds a note to the order. The same limits apply. You need the Admin permission to create credit memos.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tpay Payment is the first row of the VibeFox Tpay Payment group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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: magento-payment-tpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Tpay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that all four keys of the current environment are entered (the Sandbox keys while Sandbox mode is Yes, the production keys otherwise). Check that the cart currency is PLN. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total. The Notification URL row shows a warning when keys are missing.

The payment went through, but the order stays Pending Payment: the notification from Tpay did not reach your store or was rejected, and the customer did not come back to the store. Set Debug log to Yes and look at the log. The usual causes are a wrong Security Code or Merchant Id for the environment of the payment, a blocked notification URL (firewall, basic authentication), or a server without OpenSSL or outgoing HTTPS for the JWS check. Tpay repeats a notification until your store accepts it.

How the store answers notifications: a processed, repeated or unknown notification is answered with HTTP 200 TRUE. Otherwise Tpay sends it again later: 400 FALSE - missing with the field name, FALSE - invalid checksum (the Merchant Id or Security Code does not match the Tpay account, sandbox or production, of the payment) or FALSE - invalid JWS signature (OpenSSL is missing, the Tpay certificate cannot be downloaded or the signature is wrong; fix the server or, if needed, set JWS signature to No, the MD5 checksum is still checked); 503 FALSE - busy, retry later (the order was being updated by another request at the same moment); 500 FALSE - payment could not be recorded (an error while saving; see the log). The notification URL answers FALSE - POST only in the browser: this is normal.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by a later notification or return that reaches the store.

The customer sees Tpay payment could not be started: the keys of the current environment are wrong or Tpay rejected the request. Set Debug log to Yes; the log shows the Tpay error. If the message after Pay again is The earlier Tpay request is unconfirmed. Reconcile it before another payment., the answer of Tpay to an earlier request was lost: check the order in the Tpay panel before the customer pays again.

The customer sees This order cannot start another payment.: the order is already paid, cancelled, or a payment of its cart was already received. Check the payment in the Tpay panel.

The order is On Hold or a note asks for a review: read the note on the order, check the payment in the Tpay panel, then fulfil the order or refund the payment with Refund held Tpay payment.

A refund fails: No refundable Tpay payment is recorded. means the order has no confirmed Tpay payment. Original Tpay environment keys are missing. means the keys of the environment of the payment are missing; enter them and retry, nothing was sent. Refund exceeds actual paid funds or order total. means the amount is more than the amount not refunded yet. Refund must be a positive PLN amount with at most two decimals. means the amount is not valid. Payment is being updated. means another request is working on the same order.

A refund says Tpay refund was not confirmed, Earlier Tpay refund is unconfirmed or Accepted Tpay refund has no native Credit Memo: Tpay rejected the request, an earlier request has an uncertain result, or Tpay accepted a refund but Magento could not save its credit memo. Check the refunds in the Tpay panel, finish the refund there if needed and record it with Refund Offline.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice cannot be refunded with a credit memo; use Refund held Tpay payment on the order page.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_TpayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_TpayPayment to remove the data, then bin/magento module:disable Vibefox_TpayPayment, delete the folder app/code/Vibefox/TpayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. The cached Tpay access tokens and certificates are always removed. If Delete settings on uninstall is Yes in the Default Config, the module settings of all scopes and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Tpay payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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