VibeFox TrustPay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

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

PHP: 8.0 or later.

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 site from the internet. A firewall, maintenance mode or password protection of the site blocks the payment notifications.

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_trustpay_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > TrustPay / finby, 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 Project ID and Secret key of your live project and, for testing, of your test project (see Configuration).

6. Turn on Enable / Disable and save. Make a test payment with Test mode on, then untick Test mode to take real payments.

When you update from version 1.0, your Project ID and Secret key are kept as the live credentials and test mode is switched off. Review the settings after the update.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > TrustPay / finby. Above the fields the page warns you when the gateway is enabled but the Project ID or Secret key of the current mode is empty, and when the store currency is not supported. In both cases the payment method is hidden at checkout. In the list of payment methods, the gateway is marked as needing setup until the current mode has its Project ID and Secret key.

General

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. Default: Card payment (TrustPay).

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: Use 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.

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 an error and the previous value is kept. Secret keys are saved exactly as entered, only spaces at the start and end are removed.

Payment notifications

The order is marked paid only after finby confirms the payment with a signed notification. The plugin sends the notification URL with every payment automatically, so you do not have to set it up. The section shows the URL, for example https://your-site/wc-api/trustpay_payment_callback/. You may also enter it as the notification URL of your projects in the Merchant Portal. Notifications without a valid signature are rejected.

The plugin does not ask finby for the payment status by itself. If a notification cannot reach your site, the order stays Pending payment until finby delivers it.

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: Log API requests and notifications adds details to the log. Errors are always logged, even when this option is off. Logs are in WooCommerce > Status > Logs, source wcp_trustpay_gateway, and contain no keys, tokens, card data or customer details. Default: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). Default: off.

Checkout

The customer chooses the payment method (by default Card payment (TrustPay)) and places the order. In test mode the checkout shows Test mode: no real payment will be taken. under the description.

Card payments need the billing 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 plugin creates a card payment request at finby for the order total in the order currency. The customer's name, address and e-mail are sent for 3-D Secure, and the order ID is sent as the reference. The customer is redirected to the finby payment page and pays by card there. The page opens in the language of your store when finby supports it, otherwise in English. A note on the order shows the payment request, the amount and the project (test or live).

After paying, the customer returns to the order received page of your store, and the cart is emptied. The order is marked paid only after finby confirms it with the signed notification. The return itself never changes the payment status.

If the customer cancels on the payment page, or the payment page returns an error, the customer comes back to the Pay for order page with the message The card payment was cancelled. You can try again or choose another payment method. or The card payment was not completed. Please try again or choose another payment method. A note is added to the order. The customer can pay again from that page.

If finby cannot start the payment, the customer sees 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.

Currencies: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF and USD. HUF amounts are sent without decimals. On the Pay for order page the order currency is checked.

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 comes with English, Slovak and Czech translations.

The plugin 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, no saved cards, no subscriptions or recurring payments, no separate authorize and capture and no status polling.

Orders and refunds

Order statuses

Pending payment: the customer was sent to finby and has not paid yet, or the notification has not arrived yet.

Processing or Completed: finby confirmed the payment, and the amount and currency match the payment request and the order total. The status follows Order status after payment. The order note shows the amount, the payment request and the project. The transaction ID is the finby payment request ID.

On hold: set in three cases. The payment is still pending at finby, and the order waits for the final result. 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 order total, for example because the order was edited after the customer was sent to the payment page: check the payment before shipping. The order note explains the case.

Failed: finby rejected the latest payment of the order. The note shows the reason when finby sends it. The customer can pay again from Pay for order.

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.

Refunds

Open the order, click Refund, enter the amount and click Refund via Card payment (TrustPay) (the button shows your Title). Full and partial refunds are supported. The refund goes to the project the order was paid through (test or live), even if you have switched mode since then, so that mode's Project ID and Secret key must be set. HUF refunds must be whole amounts.

A refund is recorded only when finby accepts it. Otherwise WooCommerce shows TrustPay refused the refund: with the reason, and no refund is created. A successful refund is added to the order notes.

Refunds made in the finby Merchant Portal are not recorded as WooCommerce refunds. If finby sends a notification about them, it is added as an order note and the order status is not changed.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > TrustPay / finby. 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, the payment method 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

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 store currency, or the order currency on the Pay for order page, must be one of the supported currencies. The settings page shows a warning in both cases. Developers can change the currency list with the filter trustpay_p_supported_currencies.

The payment went through, but the order stays Pending payment: the notification did not reach your store. Check that https://your-site/wc-api/trustpay_payment_callback/ is reachable from the internet (no firewall, maintenance mode or password protection). finby retries the notification. Look at WooCommerce > Status > Logs, source wcp_trustpay_gateway.

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 store answers Invalid signature and the order is not 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 store did not create for that order, or for a project other than the one the payment was started with. The order is not changed.

The notification is answered with Busy, retry later: the order was being updated by another notification at the same moment. finby retries it.

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 On hold with an amount/currency mismatch note: the notification was authentic, but the paid amount or currency differs from the payment request or the order total. 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.

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 and the cached API access tokens are always removed. The gateway settings and the plugin logs (log files, including older rotated files, and log entries in the database) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Order data is kept: existing orders keep their payment notes, payment request IDs and transaction IDs.

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