VibeFox TrustPay 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.

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 store from the internet. A firewall, maintenance login or HTTP authentication in front of the store blocks the payment notifications.

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_trustpay_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_trustpay_gateway.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_trustpay_gateway-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 TrustPay Gateway 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 Project ID and Secret key of your test project and, for real payments, of your live project (see Configuration). The notification URL is sent with every payment, so nothing has to be set up in the Merchant Portal.

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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_trustpay_gateway.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 TrustPay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the finby projects 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 Configuration).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox TrustPay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the payment method is enabled but the Project ID or Secret key of the current mode is empty, and when the default currency of the store is not supported. In both cases the payment method is hidden at checkout. 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), Minimum total must be a number of 0 or more, and the selected geo zone and order statuses must exist. Otherwise nothing is saved and the page shows the message. 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.

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

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely by card on the TrustPay / finby payment page.

Sort order: the position of the payment method at checkout. Leave it empty or enter a whole number (negative values are allowed).

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

Minimum total: the checkout total, in the default currency of the store, that an order must reach before the payment method is offered. Leave it empty for no minimum.

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. at the Confirm Order step.

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.

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.

Order statuses

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after finby confirms it with a signed notification. Each field below lists your OpenCart order statuses. OpenCart has no own statuses for a pending or held TrustPay payment, so both use Pending by default; the order notes and the order tab tell them apart. You can create your own statuses in System > Localisation > Order Statuses and select them here.

Order status after payment: the status of a paid order. Default: Processing. Select Complete if paid orders should be completed at once. The status is set in one step, so the customer gets one e-mail.

Awaiting TrustPay payment: finby reported the latest payment as pending; the order moves to the paid status when finby confirms it. Default: Pending.

TrustPay payment on hold: the payment was only authorized (capture it in the Merchant Portal), or the paid amount or currency differs from the payment request or the order total. Default: Pending.

Payment error: finby rejected the latest payment of an order that was waiting. A later confirmed payment still moves the order to the paid status. Default: Failed.

Cancelled order status: the extension does not set it. An order in this status is never reopened by a late payment; a note is added. Default: Canceled.

Refunded order status: set after a full refund from the order page. Default: Refunded.

Payment notifications

The order is marked paid only after finby confirms it with a signed notification. The extension 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. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_trustpay_gateway/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_trustpay_gateway/payment/wcp_trustpay_gateway.callback. It is built from the storefront address of your OpenCart installation. You may also enter it as the notification URL of your projects in the Merchant Portal. Notifications without a valid signature are rejected. The URL also works while the store is in maintenance mode (on OpenCart 4 a startup action of the extension lets the notification and the customer return through).

The extension does not ask finby for the payment status by itself. If a notification cannot reach your store, the order stays without a status until finby delivers it. finby retries notifications.

Advanced

Debug logging: adds API requests and notifications to trustpay_p_debug.log.php in the OpenCart logs folder (storage/logs, on OpenCart 4 system/storage/logs). 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 extension removes the extension settings and the log. Order data is kept: orders, TrustPay payment records and refunds. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The secret keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved secret keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Card payment (TrustPay)). It is offered only when the customer's currency is one of the supported currencies: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF and USD. At the Confirm Order step the customer sees your description and the note You will be redirected to the secure TrustPay / finby payment page to pay by card. 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 card payment request at finby for the order total in the order currency. HUF amounts are sent without decimals. The customer's name, address and e-mail are sent for 3-D Secure, and the OpenCart order number is sent as the reference. 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. On OpenCart 4, which by default does not ask for a payment address, the missing fields are taken from the shipping address. The customer is redirected to the finby payment page and pays by card there. The page opens in the storefront language when finby supports it, otherwise in English.

After paying, the customer returns to your store. 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 OpenCart order success page. If not, a Payment confirmation page says TrustPay / finby is confirming your card payment. Your order is confirmed as soon as the payment is confirmed, and you will receive an e-mail — there is no need to pay again. It has a Check again button and a Back to checkout button. While the order is in the awaiting or on-hold status, the success 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. When an order in the awaiting or on-hold status is then paid, or finby rejects its payment, the customer gets the e-mail about the new order status. If finby rejected the payment or the unpaid order was cancelled, the success page shows Your card payment was not completed. Please contact us about this order. On OpenCart 4, when the customer comes back from the finby payment page, a short intermediate page opens the return address again from your store, so the cart and the customer login are kept.

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. On OpenCart 4 these messages are shown above the checkout page.

OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout. One cart is paid by one order only: once an order of the cart has a TrustPay status, confirming the cart again leads to the success page instead of a second payment. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. After a cancelled or failed payment the customer pays the same order again with a new finby payment request. If that order was closed meanwhile, the customer is sent back to the checkout, and the next Confirm Order pays a new order: after a rejected payment or a cancelled unpaid order with The card payment was not completed. Please try again or choose another payment method., otherwise (for example the order was cancelled or refunded by you) with Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

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

The extension 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 status (missing order): the customer was sent to finby and has not paid, or the notification has not arrived yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. On OpenCart 4.1 such an order can also have the status Voided, which OpenCart sets when the confirm step is shown again; the extension counts it as an order without a status.

Order status after payment (default Processing): finby confirmed the payment, and the amount and currency match the payment request and the order total. A note shows the amount, the payment request and the project (test or live).

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

TrustPay payment on hold (default Pending): 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 order total: check the payment before shipping. The note explains the case. The money was received, so a refund is available.

Payment error (default Failed): 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 order status (default Refunded): the payment was fully refunded through the extension.

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, or for another order of a cart that already has a paid order, 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.

Notes are entries in the order History that the customer does not see. They are written in the default language of the store.

VibeFox TrustPay Gateway tab

In Sales > Orders open an order paid with TrustPay. At the bottom of the order page, next to History and Additional, the VibeFox TrustPay Gateway tab shows the Payment request ID, the Payment ID, the Project with a Test project badge for test payments, the Status, the amounts Requested / paid and Paid / refunded, the refund form, the refund history, the Payment requests of this order and the TrustPay notes. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox TrustPay Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 modify the extension (set in System > Users > User Groups). 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 tab 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 order 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 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 extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox TrustPay Gateway is the first block on Extensions > Extensions > Payments > VibeFox TrustPay Gateway > 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-trustpay 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, 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. 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 by the TrustPay notification and the return to the shop, 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

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 customer's 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. Also check that the payment address is in the selected Geo zone and that the order reaches the Minimum total.

The payment went through, but the order stays without a status: the notification did not reach your store. 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 gets its status when it arrives. Errors are always written to the log; look at the Log field on the extension 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 store 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 store did not create for that order, 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 status could not be set. 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 in the on-hold status: read the notes in the VibeFox TrustPay Gateway tab (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 extension.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox TrustPay Gateway. 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, Minimum total and the order statuses, which return to their defaults on a re-install. The OpenCart event of the extension and the cached API access tokens are removed too (on OpenCart 4 its events and its startup action, which lets the notification and the customer return through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, test mode, Project IDs, secret keys, logging) and the log are removed. If it is off, they are kept for a later re-install. The TrustPay payment records 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 TrustPay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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