VibeFox MultiSafepay 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 and JSON extensions.

Currency: the order currency must be one MultiSafepay accepts, for example EUR, USD, GBP, PLN, CHF, SEK, DKK or NOK. For other currencies the payment method is hidden at checkout.

MultiSafepay account: you need the API key of your website in MultiSafepay Control. Test and live accounts have different keys. Nothing else has to be set up in MultiSafepay: the notification address is sent with every payment.

Public site: MultiSafepay must be able to reach your store to send notifications. Otherwise orders are still confirmed when the customer returns from MultiSafepay.

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-multisafepay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/MultisafepayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_MultisafepayPayment 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 MultiSafepay 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. Paste the test and/or live API key from MultiSafepay Control (see Configuration). Set Enable to Yes and click Save Config. Test a payment with Test mode = Yes, then set it to No to accept real payments.

The module adds the MultiSafepay 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 three tables for the MultiSafepay payment attempts, refunds and processed events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox MultiSafepay 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. Save Config saves the whole page. The group has no sub-sections: the fields are described below in the order of the page, under headings for orientation.

If Title is empty, Magento shows the error Enter a title for the payment method. and nothing on the page is saved.

Payment setup

The first row after the license block shows the state of the module. While Enable is Yes, it warns MultiSafepay TEST MODE: no real payments. in test mode, MultiSafepay: no API key for the current environment. when the current mode has no key (the payment method is then not shown at checkout) and MultiSafepay: store currency is not supported. when MultiSafepay does not accept the currency of your store. It always shows Notification URL: with the address that is sent to MultiSafepay with every payment. It is the storefront address of the default store view and looks like https://your-store/wcpmultisafepaygateway/webhook/index. You do not have to enter it anywhere.

General

Enable: shows or hides MultiSafepay at checkout. It is shown only when the API key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: MultiSafepay. Required.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay. HTML tags are removed.

API keys

Find the API key of your website in MultiSafepay Control. The test account (testmerchant.multisafepay.com) and the live account (merchant.multisafepay.com) have different keys. Test mode uses only the test key, live mode only the live key.

Test mode: uses the MultiSafepay test environment. It switches both the API address and the API key. No real payments are made. Payments already made keep using the environment they were made in for status checks and refunds. Default: Yes. While it is on, customers see TEST MODE: no real payment will be made. under the payment method.

Test API key: the API key of your MultiSafepay test account.

Clear saved test api key: set it to Yes and click Save Config to remove the saved test API key. It goes back to No after saving.

Live API key: the API key of your MultiSafepay live account.

Clear saved live api key: the same for the live API key.

Magento stores the keys encrypted and shows only a mask (******) after saving. Leave the mask or an empty field as it is to keep the saved key, type a new value to change it. To delete a saved key, use Clear saved test api key or Clear saved live api key.

Orders

Order status after payment: the status of a paid order.

Advanced

Debug log: writes MultiSafepay API calls and notifications to var/log/mspg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. API keys are never logged, and e-mail addresses, phone numbers and addresses are masked. Default: No.

Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The MultiSafepay payment and refund history always stays, so old orders can still be refunded. Default: No.

Conditions

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

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

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

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

Sort order: the position among the payment methods at checkout.

Debug log (the last row): shows 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 MultiSafepay) and sees the description and the note You will be redirected to MultiSafepay 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 then creates a MultiSafepay payment for the order total in the order currency and sends the customer to the MultiSafepay payment page. There the customer chooses any payment method enabled in your MultiSafepay account and pays. The billing address, e-mail, phone and the language of the store are passed to MultiSafepay, and the payment shows as Order #, the order number and the name of your store.

After paying, the customer returns to your store. The order is marked paid only after MultiSafepay confirms it: by the notification or by a check with the MultiSafepay API when the customer comes back. Magento then creates the invoice, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page with Your MultiSafepay payment has been verified. For an order on hold the page shows Your MultiSafepay payment requires review. Please do not pay again. If MultiSafepay has not confirmed the payment yet, for example while a bank transfer is awaited, the page shows Awaiting MultiSafepay payment confirmation. Your order will be updated when payment is confirmed. and a Continue payment link back to the MultiSafepay page. The notification confirms the order as soon as MultiSafepay reports the payment. A customer who comes back in another browser lands on the home page with MultiSafepay payment confirmation was checked. Please view your order details or contact the store.

If the customer cancels on the MultiSafepay page, the customer is back in the cart with The MultiSafepay payment was not completed. You may continue payment or choose another method. The cart is restored. The order stays in Pending Payment while its MultiSafepay payment is still open. If MultiSafepay reports the payment as declined, cancelled, expired or void, the order is cancelled (the stock goes back).

Before creating a new payment for the same cart, the module checks the previous one at MultiSafepay. If it is already paid or being processed, that order is used and the new order is cancelled. If it is still open with the same amount, the same payment page is reused. If the amount changed, the old payment is cancelled at MultiSafepay so it can no longer be paid, and its order is cancelled.

If MultiSafepay does not accept the payment, the order is cancelled, the cart is restored and the customer sees The MultiSafepay payment could not be started. Please choose another payment method. If the answer of MultiSafepay was lost or a previous payment cannot be checked, the customer sees a Payment confirmation page with a short message, for example The payment response was lost. Please check again; do not create another payment., and a Check again link. The technical reason is written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open MultiSafepay payment is cancelled and can no longer be paid.

The module works with the standard Magento checkout and offers one payment method that leads to the MultiSafepay page. It has no separate Magento payment methods per MultiSafepay payment method, no embedded card fields, no Apple Pay or Google Pay express buttons, no subscriptions, recurring payments or saved cards, and no capture or void from Magento. No shopping cart data is sent, so pay-later methods that require it (for example Klarna, in3 or Riverty) are not offered by MultiSafepay for these orders. MultiSafepay 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 MultiSafepay, but MultiSafepay has not confirmed the payment yet. There is no invoice.

Processing or Complete: MultiSafepay confirmed the payment (completed or shipped). The status follows Order status after payment. The invoice is created with the MultiSafepay order ID as the transaction ID, and a note shows the payment method and the environment.

On Hold before payment: the payment is uncleared (being reviewed by MultiSafepay) or reserved (authorised). Capture a reserved payment in MultiSafepay Control to receive the money. The order is released and invoiced automatically when MultiSafepay reports the payment as completed.

On Hold after payment: MultiSafepay confirmed a different amount or currency than the order total, or a test payment was completed while the module is in live mode (no real money was received). No invoice is created. The note explains it. Check the transaction in MultiSafepay Control, then fulfil the order or refund the payment.

On Hold after a chargeback: MultiSafepay reported a chargeback for a paid order: the money was taken back from your account.

Canceled: the payment was declined, cancelled, expired or voided, the payment could not be started, or the order was cancelled in Magento. A payment that arrives after the order was cancelled is noted on the order for review.

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

A paid or refunded order is never reopened by a late notification. If a second payment is completed for an order or a cart that is already paid, the order is not changed. A note asks you to refund the duplicate in MultiSafepay Control. The notes are order comments that the customer does not see.

MultiSafepay payment history

On the admin order page (Sales > Orders > View, tab Information) the MultiSafepay payment history block lists every payment attempt of the order: MultiSafepay order ID, Transaction ID, Mode (test or live), Result, Detail (the MultiSafepay status), the requested amount in the smallest currency unit, the currency and the amount and currency MultiSafepay received. The payment information of the order shows the payment method title. 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 MultiSafepay. 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 MultiSafepay.

The refund is made in the order currency, up to the amount MultiSafepay charged minus the amounts already refunded. For currencies without decimals, such as JPY or KRW, the amount is rounded the same way as the payment, and the credit memo that refunds the rest of the order returns the whole remaining amount. The refund is sent to the environment the payment was made in (test or live), so that environment's API key must be set. If MultiSafepay does not accept the refund, Magento shows MultiSafepay refund failed: with the MultiSafepay error and the credit memo is not created. A full refund closes the order. Refunds are available once MultiSafepay has confirmed the payment and the order has an invoice.

A payment that MultiSafepay received but that has no invoice (an order On Hold after a mismatch or a late payment) is refunded in the MultiSafepay payment history block: check the amount and click Refund received payment, then confirm This cannot be undone. Refund this amount? No invoice or credit memo is created. A full refund of such a payment cancels the order. This needs the Admin permission for credit memos.

MultiSafepay has no protection against sending the same refund twice. If the answer of MultiSafepay to a refund is lost, further refunds of the order are blocked with The previous refund response is uncertain. Verify it in MultiSafepay Control before any further refund. A refund that MultiSafepay accepted is never sent again when the credit memo is saved again.

Refunds made in MultiSafepay Control are added to the order notes when MultiSafepay reports them. The order and credit memos are not changed automatically. Create a credit memo with Refund Offline or update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox MultiSafepay Gateway is the first row of the VibeFox MultiSafepay Gateway group in Stores > Configuration > Sales > Payment Methods, 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-multisafepay 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, MultiSafepay 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

MultiSafepay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the current mode has an API key (Test API key in test mode, Live API key in live mode) and that MultiSafepay accepts the order currency. The Payment setup row shows a warning when the key is missing or the store currency is not accepted. 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 and that the API key of the payment's environment is set, because the module reads the status from the MultiSafepay API. If the API cannot be reached or the key is missing, the notification answers ERROR and MultiSafepay retries it. The order is also confirmed when the customer returns to the store and when the customer tries to pay the same cart again.

Notification answers Invalid request: the request had no valid transaction ID. Notifications from MultiSafepay always have one.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. MultiSafepay retries the notification later, and the order is also confirmed when the customer returns.

The customer is back in the cart with an error after Place Order: turn on Debug log and look at the Debug log row at the end of the group. The MultiSafepay payment could not be started. Please choose another payment method. usually means a wrong API key, or MultiSafepay refused the amount or currency. MultiSafepay is temporarily unavailable. Please try again. appears after an unexpected error; the reason is in the log. The order of that attempt is cancelled. When MultiSafepay cannot be reached, the customer sees the Payment confirmation page with Check again instead, and the order waits in Pending Payment.

Order is On Hold: read the order notes and the MultiSafepay payment history block. The payment may be uncleared or reserved, the paid amount or currency differed from the order, a test payment arrived in live mode, or there was a chargeback. Check the transaction in MultiSafepay Control.

Test payments do not confirm a live order: a test payment never pays an order while the module is in live mode; the order is put on hold instead. Earlier test payments are still checked and refunded with the test key after you switch to live.

Refund fails: the payment was made in the test or live environment, and the API key of that environment must be set. Provider refund totals differ from native history. Reconcile the operation in Control before another refund. means that MultiSafepay reports other refunds than Magento, for example after a refund in MultiSafepay Control or a credit memo with Refund Offline: finish the refund in MultiSafepay Control 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) is refunded with Refund received payment in the MultiSafepay payment history block.

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

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

The license key and license status are always removed. If Delete settings on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The MultiSafepay payment, refund and event history is always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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