VibeFox TrustPay 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, with the cURL extension.

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.

Currency: the order currency must be EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF or USD. For other currencies the payment method is hidden at checkout.

Reachable notification URL: finby must be able to reach your store from the internet. A firewall 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 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-trustpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/TrustpayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_TrustpayPayment 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 TrustPay Gateway. 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 Test Project ID and Test Secret key of your test project, keep Test mode at Yes, set Enable to Yes, click Save Config and place a test order. When everything works, enter the Live Project ID and Live Secret key, set Test mode to No and click Save Config.

The module adds the card payment method (by default Card payment (TrustPay)) 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 TrustPay payment attempts, the processed notifications and the refunds. The notification URL is sent to finby automatically with every payment, so nothing has to be configured in the Merchant Portal.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox TrustPay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete settings on uninstall is read from the Default Config only, so set it there. Save Config saves the whole page. Amounts are entered with a dot, for example "9.99".

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 (TrustPay title must contain 1 to 128 characters. Nothing was saved.); a Sort Order that is not a whole number (TrustPay sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (TrustPay order total must be non-negative.). A Project ID must contain 1 to 20 digits. If you save another value, the page shows TrustPay Project ID must contain 1 to 20 digits. The previous value was kept. and the other fields are saved.

While Enable is Yes, the page shows warnings near the end of the group: TrustPay is enabled but credentials of the current mode are missing. The method is hidden. and TrustPay test mode is enabled. while test mode is on. Saving the Payment Methods page also drops the cached API access tokens, so new credentials are used at once.

General

Enable: shows or hides the card payment at checkout. It is shown only when the Project ID and Secret key of the current mode are set. Default: No.

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: Text shown in the payment method list at checkout. It appears under the method when the customer selects it. 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 settings page has a link finby 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: new payments use the test project (no real payments). Default: Yes. Set it to No to take real payments with the live project. While it is on, customers see Test mode: no real payment will be taken. under the payment method. Notifications and refunds of an order always use the project the order was paid through, even after you switch the mode.

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.

Magento stores the secret keys encrypted and shows only a mask (******) after saving: Encrypted. Mask keeps the secret; clear the field to remove it. Leave the mask unchanged to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config. Secret keys are saved exactly as entered, only spaces at the start and end are removed.

Orders

Order status after payment: the order state set after a successful, confirmed payment.

Payments that finby reports as pending leave the order in Pending Payment. Amount or currency mismatches and payments that are only authorized put the order On Hold.

Conditions

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

Payment from Specific Countries: offer the card payment only for billing addresses in these countries.

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

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

Sort Order: the position among the payment methods at checkout. A whole number.

Advanced

Debug logging: adds API requests and notifications to var/log/trustpay_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Warnings and errors are always logged, even when this option is off. The log contains no request or notification bodies; secret keys, access tokens, e-mail addresses, IP addresses and card numbers are hidden. Default: No.

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 license key is always removed. Orders, invoices, credit memos and the TrustPay payment, notification and refund records are always kept. Default: No.

Payment notifications

The order is marked paid only after finby confirms it with a signed notification. The settings page shows Notification URL is sent with every payment: with the storefront notification URL of the default store view. Each payment sends the notification URL of the store view where the order was placed, which looks like https://your-store/wcptrustpaygateway/checkout/notify/, so you do not have to set it up in the Merchant Portal. It only has to be reachable from the internet. Notifications without a valid signature are rejected. The signature is checked with the Secret key of the project and mode the payment was started in.

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

Log

The last row of the group (Default Config scope) 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 Card payment (TrustPay)) and sees the description and the note You will be redirected to TrustPay to complete your payment. The method is offered only in the supported currencies: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF and USD. 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 card payment request at finby for the order total in the order currency. HUF amounts are sent without decimals. The customer's name, billing address (or the shipping address where a billing field is empty) and e-mail are sent for 3-D Secure, and the Magento order ID is sent as the reference. Every attempt gets its own payment request. The customer is redirected to the finby payment page and pays by card there. The page opens in the language of the store view when finby supports it, otherwise in English.

After paying, the customer returns to your store. The return itself never changes the payment status. If the notification has already arrived, the customer sees the standard order success page. If not, a TrustPay payment confirmation page says Your card payment is being confirmed or requires manual review. Do not pay again until the first attempt is checked. and has a Check again link. The return link contains a random token of the payment attempt and only works in the browser in which the order was placed; in another browser the customer lands in the cart.

After a confirmed payment Magento creates the invoice with the finby payment request ID as the transaction ID, the order moves to the state set in Order status after payment and the order e-mail is sent. The notification is handled even when Enable is No or the license is not active.

If the customer cancels on the payment page, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The card payment was cancelled. Your cart was restored. If the payment page returns an error, or finby has already rejected the payment, the message is The card payment was not completed. Your cart was restored. The customer can pay again or choose another payment method. An order whose payment finby reported as pending or authorized, or that has received funds, is not cancelled by such a return.

If the payment cannot be started (for example, the credentials are wrong or the address has no street, city, postcode or country), the order is cancelled, the cart is restored and the customer sees We could not start the card payment. Please try again later. in the cart. While an earlier payment of the same order or cart is still being confirmed, no second payment is started.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). finby has no API to cancel a started payment, so the module does not stop such a cancellation. If finby later reports a payment for a cancelled order, the order is not invoiced and not reopened: it stays Canceled and a note asks you to review the funds in the finby Merchant Portal.

The module works with the standard Magento checkout. It 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. It is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to finby, but finby has not confirmed the payment yet. When finby reports the payment as pending, a note says so. There is no invoice. The order is invoiced when finby confirms the payment.

Processing or Complete: finby confirmed the payment, and the amount and currency match the payment request and the order total. The state follows Order status after payment. The invoice is created 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).

On Hold: set in two cases, without an invoice. The payment was only authorized, not captured: capture or cancel it in the finby Merchant Portal. 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. A hold you set yourself is kept.

Canceled: finby rejected the latest payment of a waiting order, the customer cancelled or the payment page returned an error, the payment could not be started, or the order was cancelled in Magento. The note shows the reason when finby sends it.

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

Cancelled or closed orders are never reopened by a late payment. If a second payment arrives for an order or cart that is already paid, nothing is invoiced and a note asks you to refund the duplicate in the Merchant Portal. Chargebacks, disputes and debit notifications reported by finby are added as notes; the payment state is not changed. The notes are order comments that the customer does not see.

TrustPay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, TrustPay payment request, TrustPay payment ID, TrustPay project and TrustPay mode (test or live). The Information tab also has the TrustPay payment history with every attempt (Payment request / Payment ID, Project / Mode, Status, Requested / paid) and the TrustPay refund history. Both are shown also when the module is disabled. 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 money is sent back through finby. 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 finby.

The refund is the grand total of the credit memo in the order currency, up to the amount finby reported as paid minus the refunds already made through the module (Refund exceeds actual paid funds or order total.). HUF is sent to finby without decimals, while Magento credit memos keep two decimals: each credit memo refunds the whole-forint difference of the refunded totals, and the credit memo that refunds the rest of the order sends exactly the rest of the paid amount, so a full refund in HUF always returns what the customer paid. 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; otherwise Magento shows Restore the original TrustPay project credentials or refund in the finby Merchant Portal. and nothing is sent.

A refund counts as done only when finby accepts it. Then Magento records it on the order with a transaction ID like trustpay-p-refund-12, because finby returns no refund ID, and the refund appears in the refund history. A full refund closes the order. Otherwise Magento shows TrustPay refund was not confirmed. Reconcile in the finby Merchant Portal before retrying. and the credit memo is not created. If finby clearly refused the refund, you can try again. If no access token could be obtained from finby, nothing is sent and nothing is recorded: Magento shows TrustPay refund was not sent: no finby access token. Check the project credentials or try again later. and you can simply try again. If the refund request was sent but the result is uncertain (no answer, a server error or an unreadable answer), the refund is recorded as unconfirmed and no further online refund of this payment is sent: Magento shows Earlier TrustPay refund is unconfirmed. Reconcile before retrying. Check the refund in the Merchant Portal, refund there if needed and record it with Refund Offline.

An order on hold after an amount or currency mismatch has no invoice. Its TrustPay payment history has the field Review refund amount in the actual payment currency and the button Refund held TrustPay payment for Admin users who may create credit memos. The refund is made in the currency and up to the amount the customer actually paid; no invoice or credit memo is created, and a note records it. On success Magento shows TrustPay review refund accepted.

Refunds made in the finby Merchant Portal are not recorded in Magento. Create a credit memo with Refund Offline to record them.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox TrustPay Gateway is the first row of the VibeFox TrustPay Gateway 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-trustpay 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, the card payment 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 by the finby notification, 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

Card payment (TrustPay) does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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 settings page shows a warning when they are missing. The cart currency must be one of the supported currencies. 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 payment went through, but the order stays Pending Payment: the notification did not reach your store. Check that the store is reachable from the internet (no firewall or HTTP authentication in front of the notification URL) and that the Project ID and Secret key of the mode the payment was made in are correct. finby retries the notification, and the order is invoiced when it arrives. Turn on Debug logging and look at the Log row on the settings page.

The notification is answered with Invalid signature: the notification came from a project whose Project ID is not in the settings, or the Secret key of that project is wrong. Nothing is changed. Check the Project ID and Secret key of the mode the payment was made in. Invalid payload means the request was not a complete finby notification.

The notification is answered with 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 order was being updated at the same moment, or the order could not be saved. finby retries it. The log shows the reason.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order is invoiced by the next notification that reaches the store.

The customer is back in the cart with We could not start the card payment: turn on Debug logging and look at 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, and that the customer's address has a street, city, postcode and country. The order of that attempt is cancelled.

The order is On Hold: read the notes on the order and the TrustPay payment history (see Order statuses). Check the payment in the Merchant Portal before shipping, then fulfil the order or refund the payment.

Refund fails with Restore the original TrustPay project credentials: 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.

Refund fails with TrustPay refund was not sent: no finby access token: finby did not issue an API access token for the project the order was paid through (wrong Secret key, or finby could not be reached). Nothing was sent. Check the credentials of that project and try again.

Refund fails with Earlier TrustPay refund is unconfirmed: the result of an earlier refund request of this payment is unknown. No new refund is sent. Check the refund in the Merchant Portal, 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 (for example On Hold after a mismatch) cannot be refunded with a credit memo; use Refund held TrustPay payment in the payment history or the Merchant Portal.

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_TrustpayPayment. It removes the data and the code.

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

The license key and license status are always removed. The cached API access tokens are always removed. If Delete settings on uninstall is Yes, 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 TrustPay payment attempts, notifications 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.

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