VibeFox TrustPay for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

finby (TrustPay) account: you need a project in the finby Merchant Portal with its Project ID and Secret key. For test payments you need a separate test (playground) project with its own Project ID and Secret key. No other keys are needed: the Secret key is used both to get API access and to check the signature of payment notifications.

Reachable notification URL: finby must be able to reach your shop from the internet. A firewall, maintenance login or HTTP authentication in front of the shop blocks the payment notifications.

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 TrustPay Gateway 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 Project ID and Secret key of your test project and, for real payments, of your live project (see Configuration).

5. Turn on Enable / Disable and click Save. Make a test payment with Test mode on, then turn off Test mode to take real payments.

On install the module creates two order statuses, Awaiting TrustPay payment and TrustPay payment on hold. PrestaShop links a new payment module to the countries active at installation. For countries you add later, tick the module in Payment > Preferences. There you can also limit the module by currency and customer group.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the module is enabled but the Project ID or Secret key of the current mode is empty, and when the default currency of the shop is not supported. In both cases the payment method is hidden at checkout.

TrustPay / finby

Enable / Disable: Enable TrustPay / finby card payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Card payment (TrustPay). Required.

Description: the text shown under the payment method at checkout. Default: Pay securely by card on the TrustPay / finby payment page.

API credentials

Copy the Project ID and Secret key of your project from the finby (TrustPay) Merchant Portal. The section has a link to the Merchant Portal. Test payments use a separate test (playground) project with its own Project ID and Secret key. No real money is charged there.

Test mode: uses the test project (no real payments). New payments and refunds use the test credentials. Refunds of an order always go to the project the order was paid through. Default: on. While it is on, customers see Test mode: no real payment will be taken. under the payment method.

Live Project ID: the numeric Project ID of your live project.

Live Secret key: the Secret key of the live project. It is used to get API access tokens and to verify payment notifications.

Test Project ID: the numeric Project ID of your test (playground) project.

Test Secret key: the Secret key of the test project.

A Project ID must contain digits only. If you save another value, the page shows must contain digits only — the previous value was kept. and the other fields are saved. Secret keys are saved exactly as entered, only spaces at the start and end are removed. Saved secret keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. Saving the settings also drops the cached API access tokens, so new credentials are used at once.

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

Payment notifications

The order is marked paid only after finby confirms it with a signed notification. The module sends the notification URL with every payment automatically, so you do not have to set it up. The section shows the URL under Notification URL. With friendly URLs it looks like https://your-shop/module/wcp_trustpay_gateway/callback, possibly with a language code. You may also enter it as the notification URL of your projects in the Merchant Portal. Notifications without a valid signature are rejected.

The module does not ask finby for the payment status by itself. If a notification cannot reach your shop, no order is created until finby delivers it. finby retries notifications.

Advanced

Order status after payment: the order status set after a successful payment. The status is set in one step, so the customer gets one e-mail.

Debug logging: adds API requests and notifications to logs/trustpay_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, even when this option is off. The log contains no keys, tokens, card data or customer details. Default: off.

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. Order data is kept: orders, TrustPay payment records and refunds, and the order statuses. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Card payment (TrustPay)) and confirms the order. The payment method is offered only in the supported currencies: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF and USD. HUF amounts are sent without decimals.

Card payments need an address. If the street, city, postcode or country is missing, the customer sees Please enter your billing address (street, city, postcode and country) — it is required for card payments.

The module creates a card payment request at finby for the cart total in the cart currency. The customer's name, address and e-mail are sent for 3-D Secure, and the cart number is sent as the reference. No order exists yet at this point. The customer is redirected to the finby payment page and pays by card there. The page opens in the language of the cart when finby supports it, otherwise in English.

After paying, the customer returns to your shop. The order is marked paid only after finby confirms it with the signed notification. The return itself never changes the payment status. If the notification has already arrived, the customer sees the standard order confirmation page. If not, a Payment confirmation page says that finby is confirming the card payment and that the order is created as soon as it is confirmed. It has a Check again button and a Back to checkout button. While the order is Awaiting TrustPay payment or TrustPay payment on hold, the confirmation page shows Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. If finby rejected the payment or the unpaid order was cancelled, it shows Your card payment was not completed. Please contact us about this order.

If the customer cancels on the payment page, the customer is back at checkout with The card payment was cancelled. You can try again or choose another payment method. If the payment page returns an error, or finby has already rejected the payment, the message is The card payment was not completed. Please try again or choose another payment method. The cart is kept and the customer can pay again.

If finby cannot start the payment, the customer stays at checkout with We could not start the card payment. Please try again in a moment or choose another payment method. The technical reason is written to the log.

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

The module takes card payments only, as a one-step purchase on the finby page. It has no bank transfers or other finby payment methods, no Apple Pay or Google Pay buttons on your site, no saved cards, no subscriptions or recurring payments, no separate authorize and capture and no status polling.

Orders and refunds

Order statuses

No order yet: the customer was sent to finby and has not paid, or the notification has not arrived yet. Only the cart exists.

Payment accepted or Delivered: finby confirmed the payment, and the amount and currency match the payment request and the cart total. The status follows Order status after payment. The payment is recorded with the finby payment request ID as the transaction ID, and a note shows the amount, the payment request and the project (test or live).

Awaiting TrustPay payment: finby reported the latest payment as pending. The order moves to the paid status when finby confirms the payment.

TrustPay payment on hold: set in two cases. The payment was only authorized, not captured: capture or cancel it in the finby Merchant Portal, then update the order. Or the paid amount or currency differs from the payment request or the cart total, for example because the cart was changed after the customer was sent to the payment page: check the payment before shipping. The note explains the case.

Payment error: finby rejected the latest payment of an order that was waiting. The note shows the reason when finby sends it. A later confirmed payment still moves the order to the paid status.

Refunded: the payment was fully refunded through the module.

Cancelled or refunded orders are never reopened by a late payment. A note asks you to reinstate the order or refund the payment in the Merchant Portal. If a second payment arrives for an order that is already paid, the order is not changed and a note asks you to refund the duplicate in the Merchant Portal. Chargebacks and disputes reported by finby are added as notes.

TrustPay / finby payment block

The order page shows a TrustPay / finby payment block with the payment request ID, the finby payment ID, the project, the payment status, the requested and paid amounts, the amount refunded, a Test project badge for test payments, the refund history and the TrustPay notes of the order.

Refunds

In the TrustPay / finby payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via TrustPay. Confirm the question Refund this amount through TrustPay? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. Refunds are made in the amount and currency finby reported for the payment, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. HUF refunds must be whole amounts.

The refund goes to the project the order was paid through (test or live), even if you have switched mode since then. That project's Project ID and Secret key must be set, and its Project ID must not have changed. A refund is recorded only when finby accepts it. Otherwise the block shows TrustPay refused the refund: with the reason, and no refund is recorded. A successful refund is added to the refund history and the notes. A full refund 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 finby. Refunds made in the finby Merchant Portal are not recorded as refunds. If finby sends a notification about them, it is added as a note and the order status is not changed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox TrustPay Gateway is the first block on Modules > Module Manager > VibeFox TrustPay Gateway > 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-trustpay 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, the card payment 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 by the TrustPay notification and the return to the shop, 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

Card payment (TrustPay) does not appear at checkout: check that the license is active, Enable / Disable is on and the current mode has its Project ID and Secret key: Test Project ID and Test Secret key in test mode, Live Project ID and Live Secret key in live mode. The cart currency must be one of the supported currencies. The settings page shows a warning when the credentials are missing or the default currency is not supported. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the notification did not reach your shop. Check that the URL shown under Notification URL is reachable from the internet (no firewall, maintenance login or HTTP authentication). finby retries the notification, and the order is created when it arrives. Turn on Debug logging and look at the Log field on the module page.

The log shows Notification rejected: invalid signature or unknown project: the notification came from a project whose Project ID is not in the settings, or the Secret key of that project is wrong. The shop answers Invalid signature and nothing is changed. Check the Project ID and Secret key of the mode the payment was made in.

The log shows Notification ignored: the notification belongs to a payment request that this shop did not create for that cart, or to another project or mode than the one the payment was started with. Nothing is changed.

The notification is answered with Busy, retry later or Temporary error: the cart was being updated by another notification at the same moment, or the order could not be created (for example, the module is disabled). finby retries it. The log shows the reason.

The customer sees We could not start the card payment: open the log. A wrong Project ID or Secret key gives a message that finby rejected the credentials of the project. Check that test credentials are in the test fields and live credentials in the live fields.

Card payment is temporarily unavailable: the customer sees this when the current mode has no Project ID or Secret key. Enter them and save.

Order is TrustPay payment on hold: read the notes in the TrustPay / finby payment block (see Order statuses). Check the payment in the Merchant Portal before shipping, then fulfil the order or refund the payment.

Refund fails with a message about the project: the order was paid through the test or live project, and the Project ID or Secret key of that mode is not set, or another Project ID is saved there now. Enter the credentials of that project, or refund the payment in the finby Merchant Portal.

Invalid refund amount: at most … can be refunded: the amount is more than the paid amount minus the refunds already made through the module.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox TrustPay Gateway and choose Uninstall. The license key and license status of this module are always removed. The cached API access tokens are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The TrustPay payment records and refunds and the order statuses Awaiting TrustPay payment and TrustPay 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.

TrustPay and finby are trademarks of their respective owners. This module is not affiliated with or endorsed by TrustPay or finby.